From: Alexander Ebert <ebert@woltlab.com>
Date: Sat, 22 Jun 2024 23:26:53 +0000 (+0200)
Subject: Add the documentation for the TypeScript RPC API
X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=b7b3713292d6e22efb2758e75e8cb982b52d6992;p=GitHub%2FWoltLab%2Fwoltlab.github.io.git

Add the documentation for the TypeScript RPC API
---

diff --git a/docs/javascript/components_rpc_api.md b/docs/javascript/components_rpc_api.md
new file mode 100644
index 00000000..be18b971
--- /dev/null
+++ b/docs/javascript/components_rpc_api.md
@@ -0,0 +1,70 @@
+# RPC API
+
+The [PHP RPC API](../php/api/rpc_api.md) has a companion implementation in TypeScript that greatly simplifies the communication with the server and provides helper methods to process responses.
+
+# Implementing the API
+
+## Naming Schema
+
+The module should roughly map to the route parameters for simplicity, for example, `WoltLabSuite/Core/Api/Sessions/DeleteSession` maps to the `DELETE /sessions/:id` endpoint.
+
+## Using `WoltLabSuite/Core/Api/Result`
+
+The `Result` module provides a consistent interface to interact with the API.
+A comprehensive implementation can be found in `WoltLabSuite/Core/Api/Comments/RenderComment.ts`:
+
+```ts
+import { prepareRequest } from "WoltLabSuite/Core/Ajax/Backend";
+import { ApiResult, apiResultFromError, apiResultFromValue } from "../Result";
+
+type Response = {
+  template: string;
+  response: string | undefined;
+};
+
+export async function renderComment(
+  commentId: number,
+  responseId: number | undefined = undefined,
+  messageOnly: boolean = false,
+  objectTypeId: number | undefined = undefined
+): Promise<ApiResult<Response>> {
+  const url = new URL(
+    `${window.WSC_API_URL}index.php?api/rpc/core/comments/${commentId}/render`
+  );
+  url.searchParams.set("messageOnly", messageOnly.toString());
+  if (responseId !== undefined) {
+    url.searchParams.set("responseID", responseId.toString());
+  }
+  if (objectTypeId !== undefined) {
+    url.searchParams.set("objectTypeID", objectTypeId.toString());
+  }
+
+  let response: Response;
+  try {
+    response = (await prepareRequest(url).get().fetchAsJson()) as Response;
+  } catch (e) {
+    return apiResultFromError(e);
+  }
+
+  return apiResultFromValue(response);
+}
+```
+
+For `GET` and `DELETE` parameters it is possibly to provide additional parameters using the query string.
+You should use the native `URL` class to (conditionally) set those parameters as shown in the example above.
+
+### `ApiResult`
+
+The type `ApiResult` represents the two possible states of the response, either an error or the actual result.
+The callee should evaluate the `ok` property to distinguish between the two cases to properly handle any rejections.
+
+Sometimes an action is infallible by design in which case the shortcut `.unwrap()` should be used.
+It will return the result value or fail hard when there is an actual error.
+
+#### `apiResultFromError(error: unknown)`
+
+This function checks if the `error` represents a server response that is not in the 2xx range.
+Any network errors or other kind of client errors will fail hard.
+
+The returned value from the server will be attempted to be parsed into an `WoltLabSuite/Core/Api/Error` that represents the well-defined error response from the PHP RPC API.
+Validation errors can easily be detected through the `.getValidationError()` method of `ApiError` which returns `undefined` for all other error classes.
diff --git a/docs/php/api/rpc_api.md b/docs/php/api/rpc_api.md
index 81837912..f0fd6da2 100644
--- a/docs/php/api/rpc_api.md
+++ b/docs/php/api/rpc_api.md
@@ -143,3 +143,7 @@ Expects `$className` to be derived from `wcf\data\DatabaseObject` and attempts t
 Afterwards the object is tested to have a non-falsy object id, otherwise a `UserInputException` is raised.
 
 Returns the fetched object on success.
+
+# Interacting with the PHP RPC API in TypeScript
+
+You can find an introduction to the [TypeScript API for the RPC API](../../javascript/components_rpc_api.md) in the documentation.
diff --git a/mkdocs.yml b/mkdocs.yml
index c953f07f..4ceaab3e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -39,6 +39,7 @@ nav:
               - "Validation and Data": "php/api/form_builder/validation_data.md"
               - "Dependencies": "php/api/form_builder/dependencies.md"
           - "Package Installation Plugins": "php/api/package_installation_plugins.md"
+          - "RPC API": "php/api/rpc_api.md"
           - "User Activity Points": "php/api/user_activity_points.md"
           - "User Notifications": "php/api/user_notifications.md"
           - "RSS Feeds": "php/api/rss_feeds.md"
@@ -64,6 +65,7 @@ nav:
           - "Google Maps": "javascript/components_google_maps.md"
           - "Notices": "javascript/components_notice.md"
           - "Pagination": "javascript/components_pagination.md"
+          - "RPC API": "javascript/components/rpc_api.md"
       - "New API":
           - "Writing a module": "javascript/new-api_writing-a-module.md"
           - "Core Functions": "javascript/new-api_core.md"