From 1fe5cca6208381a67b5d6b45d76e7a7536144ded Mon Sep 17 00:00:00 2001 From: Afsal Thaj Date: Wed, 14 May 2025 09:20:48 -0600 Subject: [PATCH 1/4] fix links --- .../worker-filesystem.mdx | 2 +- src/pages/concepts/api-definitions.mdx | 2 +- src/pages/http-api-definitions.mdx | 6 ++--- ...-types.mdx => api-definition-bindings.mdx} | 22 ++++--------------- src/pages/invoke/making-custom-apis.mdx | 8 +++---- .../making-custom-apis/authentication.mdx | 2 +- .../making-custom-apis/expose-http-apis.mdx | 4 ++-- 7 files changed, 16 insertions(+), 30 deletions(-) rename src/pages/http-api-definitions/{worker-binding-types.mdx => api-definition-bindings.mdx} (93%) diff --git a/src/pages/common-language-guide/worker-filesystem.mdx b/src/pages/common-language-guide/worker-filesystem.mdx index 33c4d200..3e8b5061 100644 --- a/src/pages/common-language-guide/worker-filesystem.mdx +++ b/src/pages/common-language-guide/worker-filesystem.mdx @@ -305,5 +305,5 @@ use the `golem:api/save-snapshot` function to persist the files and later restor ## Externally accessing worker files -You can use [file-server worker bindings](/http-api-definitions/worker-binding-types) to automatically deploy a REST API that allows accessing the files +You can use [file-server worker bindings](/http-api-definitions/api-definition-bindings) to automatically deploy a REST API that allows accessing the files on a worker filesystem. diff --git a/src/pages/concepts/api-definitions.mdx b/src/pages/concepts/api-definitions.mdx index a0cc6ce1..921f55fb 100644 --- a/src/pages/concepts/api-definitions.mdx +++ b/src/pages/concepts/api-definitions.mdx @@ -59,7 +59,7 @@ Bindings are the glue that connects your endpoint to an actual worker. Examples of what binding can do include invoking a worker, retrieving files from the worker filesystem and forwarding http requests to the wasi:http/proxy world. -There are many different binding types that address various usecases, learn more about them [here](/http-api-definitions/worker-binding-types). +There are many different binding types that address various usecases, learn more about them [here](/http-api-definitions/api-definition-bindings). # Management diff --git a/src/pages/http-api-definitions.mdx b/src/pages/http-api-definitions.mdx index fd404983..6c582449 100644 --- a/src/pages/http-api-definitions.mdx +++ b/src/pages/http-api-definitions.mdx @@ -1,5 +1,5 @@ -# API Definitions reference +# API Definition Reference -Learn mor about API definitions: +Learn more about API definition bindings here: -- [Worker binding types](/http-api-definitions/worker-binding-types.mdx) +- [API definition binding types](/http-api-definitions/api-definition-bindings.mdx) diff --git a/src/pages/http-api-definitions/worker-binding-types.mdx b/src/pages/http-api-definitions/api-definition-bindings.mdx similarity index 93% rename from src/pages/http-api-definitions/worker-binding-types.mdx rename to src/pages/http-api-definitions/api-definition-bindings.mdx index b4d0ab5a..c2cf328e 100644 --- a/src/pages/http-api-definitions/worker-binding-types.mdx +++ b/src/pages/http-api-definitions/api-definition-bindings.mdx @@ -1,8 +1,8 @@ -# Worker Binding Types +# API definition Binding Types ## Overview -The Worker Binding Types are a collection of different ways that a worker can be exposed to the outside world as part of an api definition. +The binding types are a collection of different ways that a worker can be exposed to the outside world as part of an api definition. To get a basic introduction of what api-definitions are and how bindings fit into them, please read the defining custom apis [guide](/invoke/making-custom-apis). @@ -18,9 +18,6 @@ The default and most basic binding type that allows invoking workers in custom w Example: ```yaml -id: example-api -version: 0.0.1 -createdAt: 2024-08-21T07:42:15.696Z routes: - method: Get # Define the path that the route will apply to. {var} patterns capture the path segments and make it available for scripts. @@ -28,10 +25,9 @@ routes: binding: component: name: checkout-component - # Use the variable captured from the path to resolve the worker to call - worker-name: 'let name: string = request.path.cart-id; name' - # Invoke functions on the worker to handle the request and construct the response response: | + let name = request.path.cart-id; + let worker = instance(name); let response = golem:it/api.{{checkout}}(); let status: u64 = 200; {{headers: {{ContentType: "json"}}, body: response, status: status}} @@ -60,9 +56,6 @@ regarding CORS, see the [mdn docs](https://developer.mozilla.org/en-US/docs/Glos Example: ```yaml -id: example-api -version: 0.0.1 -createdAt: 2024-08-21T07:42:15.696Z routes: - method: Options path: /users/{user-id} @@ -103,9 +96,6 @@ To learn more about the worker filesystem, check out the [dedicated guide](/comm Example: ```yaml -id: example-api -version: 0.0.1 -createdAt: 2024-08-21T07:42:15.696Z routes: - method: Get # {+var} patterns capture all remaining path segments @@ -114,7 +104,6 @@ routes: bindingType: file-server component: name: example-component - workerName: 'let name: string = request.path.worker-name; name' # retrieve the path /files/${{file}} from the worker and return the content. response: 'let file: string = request.path.file; "/files/${{file}}"' ``` @@ -152,9 +141,6 @@ The binding will forward the incoming requests to the worker and return the resp Example: ```yaml -id: example-api -version: 0.0.1 -createdAt: 2024-08-21T07:42:15.696Z # Each user has it's own worker that directly implements the user api using wasi:http/incoming-handler. # Define routes to forward the traffic to the workers. routes: diff --git a/src/pages/invoke/making-custom-apis.mdx b/src/pages/invoke/making-custom-apis.mdx index 3fb867dd..1ef2eada 100644 --- a/src/pages/invoke/making-custom-apis.mdx +++ b/src/pages/invoke/making-custom-apis.mdx @@ -10,10 +10,10 @@ For reference, see the [API Definition Reference](/http-api-definitions) page. ### API Development Workflow 1. **[Create a component](making-custom-apis/create-simple-component)**: Learn how to create a new API definition. -2. **[Expose Http APIs for your Golem App](making-custom-apis/expose-http-apis)**: Learn how to create a new API definition. -3. **[Update Http APIs](making-custom-apis/update-api-deployment)**: Make changes to existing APIs and redeploy. -4. **[Authenticated Http APIs APIs](making-custom-apis/authentication)**: Configure authentication mechanisms for your API. -5. **[CORS for Http APIs](making-custom-apis/cors)**: Set up Cross-Origin Resource Sharing (CORS) policies. +2. **[Expose HTTP APIs for your Golem App](making-custom-apis/expose-http-apis)**: Learn how to create a new API definition. +3. **[Update HTTP APIs](making-custom-apis/update-api-deployment)**: Make changes to existing APIs and redeploy. +4. **[Authenticated HTTP APIs APIs](making-custom-apis/authentication)**: Configure authentication mechanisms for your API. +5. **[CORS for HTTP APIs](making-custom-apis/cors)**: Set up Cross-Origin Resource Sharing (CORS) policies. 6. **[Customise Http Responses with Rib](making-custom-apis/rib-in-api-definition)**: Use Rib for customizing API response mappings. 7. **[Automatic Documentation for Endpoints](making-custom-apis/spec-inference)**: Learn more on automatic spec generation based on Rib scripts. 8. **[Constraints on Component Updates](making-custom-apis/component-constraints)**: Learn more on restrictions for updating components after deployment. diff --git a/src/pages/invoke/making-custom-apis/authentication.mdx b/src/pages/invoke/making-custom-apis/authentication.mdx index a67a7e36..60d7f25c 100644 --- a/src/pages/invoke/making-custom-apis/authentication.mdx +++ b/src/pages/invoke/making-custom-apis/authentication.mdx @@ -1,6 +1,6 @@ import { Steps } from "nextra/components" -# Make Secure Http APIs +# Make Secure HTTP APIs Golem API gateway has built-in authentication support to identify users using OpenID protocol. This allows you to refer to the claims such as `request.auth.email` (as an example) once authenticated in your Rib expression. diff --git a/src/pages/invoke/making-custom-apis/expose-http-apis.mdx b/src/pages/invoke/making-custom-apis/expose-http-apis.mdx index 6aa8480e..e774041b 100644 --- a/src/pages/invoke/making-custom-apis/expose-http-apis.mdx +++ b/src/pages/invoke/making-custom-apis/expose-http-apis.mdx @@ -1,4 +1,4 @@ -## Expose Http APIs for your Golem App +## Expose HTTP APIs for your Golem App The first step to exposing your the functions in your component (in short, worker functions) as http apis, is to edit the manifest golem.yaml to add an API definition. @@ -90,7 +90,7 @@ Let's break down the binding object. | `component` | Specifies the component's name and version | | `response` | The `response` field here is a Rib expression that allows you to call any worker function and manipulates its output. | -See the [binding type reference](/http-api-definitions/worker-binding-types) for more details on the supported binding types. +See the [binding type reference](/http-api-definitions/api-definition-bindings) for more details on the supported binding types. If your worker name is a constant, the you can simply make it a constant string such as `"foo"`. Please note that it has to be quoted for it a valid Rib string. See the [Rib reference](/rib) for the full reference of the binding language. From e26747b861db3be0387cc3a71d39a5a23c6a443e Mon Sep 17 00:00:00 2001 From: Afsal Thaj Date: Wed, 14 May 2025 09:34:46 -0600 Subject: [PATCH 2/4] fix docs --- .../api-definition-bindings.mdx | 26 +++++++------------ 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/src/pages/http-api-definitions/api-definition-bindings.mdx b/src/pages/http-api-definitions/api-definition-bindings.mdx index c2cf328e..79cb5c88 100644 --- a/src/pages/http-api-definitions/api-definition-bindings.mdx +++ b/src/pages/http-api-definitions/api-definition-bindings.mdx @@ -23,8 +23,8 @@ routes: # Define the path that the route will apply to. {var} patterns capture the path segments and make it available for scripts. path: /carts/{cart-id}/checkout binding: - component: - name: checkout-component + type: default + componentName: checkout-component response: | let name = request.path.cart-id; let worker = instance(name); @@ -60,14 +60,13 @@ routes: - method: Options path: /users/{user-id} binding: - bindingType: cors-preflight + type: cors-preflight # Another definition for the same route and a different method. # The cors-preflight binding will enable cors for this binding. - method: Get path: /users/{user-id} binding: - component: - name: example-component + componentName: example-component response: | {status: 200u64, body: "Hello World"} ``` @@ -101,9 +100,8 @@ routes: # {+var} patterns capture all remaining path segments path: /workers/{worker-name}/files/{+file} binding: - bindingType: file-server - component: - name: example-component + type: file-server + componentName: example-component # retrieve the path /files/${{file}} from the worker and return the content. response: 'let file: string = request.path.file; "/files/${{file}}"' ``` @@ -147,18 +145,14 @@ routes: - method: Get path: /users/{user} binding: - bindingType: http-handler - component: - name: user-component - version: 0 + type: http-handler + componentName: user-component workerName: 'let name: string = request.path.user; name' - method: Get path: /users/{user}/{+user-route} binding: - bindingType: http-handler - component: - name: user-component - version: 0 + type: http-handler + componentName: user-component workerName: 'let name: string = request.path.user; name' ``` From 5492f842e14fb3e2895ea687693a8e2dc9e750d2 Mon Sep 17 00:00:00 2001 From: Afsal Thaj Date: Wed, 14 May 2025 09:47:33 -0600 Subject: [PATCH 3/4] fix docs --- .../api-definition-bindings.mdx | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/pages/http-api-definitions/api-definition-bindings.mdx b/src/pages/http-api-definitions/api-definition-bindings.mdx index 79cb5c88..6cf93934 100644 --- a/src/pages/http-api-definitions/api-definition-bindings.mdx +++ b/src/pages/http-api-definitions/api-definition-bindings.mdx @@ -71,6 +71,34 @@ routes: {status: 200u64, body: "Hello World"} ``` +You can customise the CORS by providing a `response` Rib script which should be a record that contains CORS parameters + +```yaml +routes: + - method: Options + path: /users/{user-id} + binding: + type: cors-preflight + response: | + { + Access-Control-Allow-Origin: "mysite.com", + Access-Control-Allow-Methods: "GET, POST, PUT, DELETE, OPTIONS", + Access-Control-Allow-Headers: "Content-Type, Authorization", + Access-Control-Expose-Headers: "Content-Length, X-Requested-With", + Access-Control-Allow-Credentials: true, + Access-Control-Max-Age: 86400u64 + } + # Another definition for the same route and a different method. + # The cors-preflight binding will enable cors for this binding. + - method: Get + path: /users/{user-id} + binding: + componentName: example-component + response: | + {status: 200u64, body: "Hello World"} +``` + + Parameters: | Parameter | Required | Type | Description | From 8bbce18e28080ce93b4aed2e611a237a262f8081 Mon Sep 17 00:00:00 2001 From: Afsal Thaj Date: Wed, 14 May 2025 09:49:55 -0600 Subject: [PATCH 4/4] fix parameters --- .../api-definition-bindings.mdx | 24 ++++--------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/src/pages/http-api-definitions/api-definition-bindings.mdx b/src/pages/http-api-definitions/api-definition-bindings.mdx index 6cf93934..af0c35b1 100644 --- a/src/pages/http-api-definitions/api-definition-bindings.mdx +++ b/src/pages/http-api-definitions/api-definition-bindings.mdx @@ -37,8 +37,7 @@ Parameters: | Parameter | Required | Type | Description | | ----------------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| component.name | true | string | Name of the component to invoke | -| component.version | false | number | Version of the component to invoke. If not provided, the latest version is used. | +| componentName | true | string | Name of the component to invoke | | workerName | false | rib | Script used to compute the name of the worker that will be invoked. The script has access to the request input. If not provided, an ephemeral worker is used. | | idempotencyKey | false | rib | Script used to compute the idempotency key. The script has access to the request input. If not provided an idempotency key will be generated. | | response | true | rib | Script that is used to compute the response that will be returned to the user. The script has access to the request and worker inputs and can call worker functions. The result of the script has to be an object with status and optional headers and body fields. | @@ -71,7 +70,7 @@ routes: {status: 200u64, body: "Hello World"} ``` -You can customise the CORS by providing a `response` Rib script which should be a record that contains CORS parameters +For customisation of CORS parameters, provide `response` Rib script which should be a record with CORS headers as keys ```yaml routes: @@ -97,18 +96,7 @@ routes: response: | {status: 200u64, body: "Hello World"} ``` - - -Parameters: - -| Parameter | Required | Type | Description | -| ---------------- | -------- | ------ | ---------------------------------------------------------------------------------------------------------------- | -| allowOrigin | false | string | Value of the Access-Control-Allow-Origin header. Defaults to "\*" if not provided. | -| allowMethods | false | string | Value of the Access-Control-Allow-Methods header. Defaults to "GET, POST, PUT, DELETE, OPTIONS" if not provided. | -| allowHeaders | false | string | Value of the Access-Control-Allow-Headers header. Defaults to "Content-Type, Authorization" if not provided. | -| exposeHeaders | false | string | Value of the Access-Control-Expose-Headers. | -| maxAge | false | string | Value of the Access-Control-Max-Age header. | -| allowCredentials | false | string | Value of the Access-Control-Allow-Credentials header. | + | ### File Server @@ -138,8 +126,7 @@ Parameters: | Parameter | Required | Type | Description | | ----------------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| component.name | true | string | Name of the component to invoke | -| component.version | false | number | Version of the component to invoke. If not provided, the latest version is used. | +| componentName | true | string | Name of the component to invoke | | workerName | false | rib | Script used to compute the name of the worker that will be invoked. The script has access to the request input. If not provided, an ephemeral worker is used. | | idempotencyKey | false | rib | Script used to compute the idempotency key. The script has access to the request input. If not provided an idempotency key will be generated. | | response | true | rib | Script that is used to compute the file to retrieve and the response to send to users. See the dedicatedc [section](#file-server-response-object) for more details. | @@ -188,7 +175,6 @@ Parameters: | Parameter | Required | Type | Description | | ----------------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| component.name | true | string | Name of the component to invoke | -| component.version | false | number | Version of the component to invoke. If not provided, the latest version is used. | +| componentName | true | string | Name of the component to invoke | | workerName | false | rib | Script used to compute the name of the worker that will be invoked. The script has access to the request input. If not provided, an ephemeral worker is used. | | idempotencyKey | false | rib | Script used to compute the idempotency key. The script has access to the request input. If not provided an idempotency key will be generated. |