From beaf4d3d7023702e3fbb0e3f4c17ac124e538ddb Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Thu, 8 May 2025 16:01:21 +0200 Subject: [PATCH 01/65] docs: adds article on working with the Fetch API --- .../foundation/fetching-data/fetch-api.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md new file mode 100644 index 00000000000..778fa8cdeea --- /dev/null +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -0,0 +1,148 @@ +--- +description: The Fetch API is a modern way to make network requests in JavaScript. It provides a more powerful and flexible feature set than the older XMLHttpRequest. +--- + +# Fetch API + +The [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) is a Promise-based API that allows you to make network requests similar to XMLHttpRequest. It is a modern way to make network requests in JavaScript and provides a more powerful and flexible feature set than the older XMLHttpRequest. It is available in all modern browsers and is the recommended way to make network requests in JavaScript. + +## Fetch API in Umbraco + +The Fetch API can also be used in Umbraco to make network requests to the server. Since it is built into the browser, you do not need to install any additional libraries or packages to use it. The Fetch API is available in the global scope and can be used directly in your JavaScript code. +The Fetch API is a great way to make network requests in Umbraco because it provides a lot of flexibility. You can use it to make GET, POST, PUT, DELETE, and other types of requests to the server. You can also use it to handle responses in a variety of formats, including JSON, text, and binary data. + +### Example + +For this example, we are using the Fetch API to make a GET request to the `/umbraco/MyApiController/GetData` endpoint. The response is then parsed as JSON and logged to the console. If there is an error with the request, it is caught and logged to the console: + +```javascript +const data = await fetch('/umbraco/MyApiController/GetData') + .then(response => { + if (!response.ok) { + throw new Error('Network response was not ok'); + } + return response.json(); + }) + .catch(error => { + console.error('There was a problem with the fetch operation:', error); + }); + +if (data) { + console.log(data); // Do something with the data +} +``` + +{% hint style="info" %} +The example assumes that you have a controller set up at the `/umbraco/MyApiController/GetData` endpoint that returns JSON data. You can replace this with your own endpoint as needed. Read more about creating a controller in the [Controllers](../../../implementation/controllers.md) article. +{% endhint %} + +## Authentication + +When making requests to the Umbraco API controllers, you may need to include an authorization token in the request headers. This is especially important when making requests to endpoints that require authentication. + +The Fetch API does not automatically include authentication tokens in requests. You need to manually add the authentication token to the request headers. This can be done by adding an `Authorization` header to the request: + +```javascript +const token = 'your-auth-token'; +const data = await fetch('/umbraco/MyApiController/GetData', { + method: 'GET', + headers: { + 'Authorization': `Bearer ${token}`, + 'Content-Type': 'application/json' + } +}); +``` + +{% hint style="info" %} +The example assumes that you have a valid authentication token. You can replace this with your own token as needed. Read more about authentication in the [Security](../../../implementation/security.md) article. +{% endhint %} + +## Management API Controllers + +The Fetch API can also be used to make requests to the Management API controllers. The Management API is a set of RESTful APIs that allow you to interact with Umbraco programmatically. You can use the Fetch API to make requests to the Management API controllers like you would with any other API. The Management API controllers are located in the `/umbraco/api/management` namespace. You can use the Fetch API to make requests to these controllers like you would with any other API. + +### API User + +You can create an API user in Umbraco to authenticate requests to the Management API. This is useful for making requests from external applications or services. You can create an API user in the Umbraco backoffice by going to the Users section and creating a new user with the "API" role. Once you have created the API user, you can make requests to the Management API using the API user's credentials. You can find these in the Umbraco backoffice. + +You can read more about this concept in the [API Users](../../../fundamentals/data/users/api-users.md) article. + +### Backoffice Token + +The Fetch API can also be used to make requests to the Management API using a Backoffice token. This is useful for making requests from custom components that are running in the Backoffice. The concept is similar to the API Users, but the Backoffice token represents the current user in the Backoffice. You will share the access policies of the current user, so you can use the token to make requests on behalf of the current user. + +To use the Backoffice access token, you will have to consume the **UMB_AUTH_CONTEXT** context. This context is only available in the Backoffice and includes tools to hook on to the authentication process. You can use the [getOpenApiConfiguration](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_auth.UmbAuthContext.html#getopenapiconfiguration) method to get a configuration object that includes a few useful properties: + +- `base`: The base URL of the Management API. +- `credentials`: The credentials to use for the request. +- `token()`: A function that returns the current access token. + +Read more about this in the [UmbOpenApiConfiguration](https://apidocs.umbraco.com/v16/ui-api/interfaces/packages_core_auth.UmbOpenApiConfiguration.html) interface. + +It is rather tiresome to manually add the token to each request. Therefore, you can wrap the Fetch API in a custom function that automatically adds the token to the request headers. This way, you can use the Fetch API without worrying about adding the token manually: + +```typescript +import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth'; +import type { UmbClassInterface } from '@umbraco-cms/backoffice/class-api'; + +/** + * Make an authorized request to any Backoffice API. + * @param host A reference to the host element that can request a context. + * @param url The URL to request. + * @param method The HTTP method to use. + * @param body The body to send with the request (if any). + * @returns The response from the request as JSON. + */ +async function makeRequest(host: UmbClassInterface, url: string, method = 'GET', body?: any) { + const authContext = await host.getContext(UMB_AUTH_CONTEXT); + const token = await authContext.getLatestToken(); + const response = await fetch(url, { + method, + body: body ? JSON.stringify(body) : undefined, + headers: { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${token}`, + }, + }); + return response.json(); +} +``` + +The above example serves to illustrate some of the process to make a request to the Management API. You can use this function to make requests to any endpoint in the Management API. The function does not handle errors or responses, so you will need to add that logic yourself, nor does it handle the authentication process. If the token is timed out, you will get a 401 error back, if the `getLatestToken` method failed to refresh the token. + +## Executing the request + +Regardless of method, you can execute the fetch requests through Umbraco's [tryExecute](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_auth.UmbAuthContext.html#tryexecute) function. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again. + +```javascript +import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth'; +import { tryExecute } from '@umbraco-cms/backoffice/resources'; + +const authContext = await this.getContext(UMB_AUTH_CONTEXT); +const token = await authContext.getLatestToken(); +const request = fetch(url, { + method, + body: body ? JSON.stringify(body) : undefined, + headers: { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${token}`, + }, +}); +const { data, error } = await tryExecute(this, request); + +if (error) { + console.error('There was a problem with the fetch operation:', error); +} else { + console.log(data); // Do something with the data +} +``` + +{% hint style="info" %} +The above example requires a host element illustrated by the use of `this`. This is typically a custom element that extends the `UmbLitElement` class. +{% endhint %} + +## Conclusion + +The Fetch API is a powerful and flexible way to make network requests in JavaScript. It is available in all modern browsers and is the recommended way to make network requests in JavaScript. The Fetch API can be used in Umbraco to make network requests to the server. It can also be used to make requests to the Management API controllers. You can use the Fetch API to make requests to any endpoint in the Management API. You can also use it to handle responses in a variety of formats. This is especially useful, if you have but a few requests to make. + +However, if you have a lot of requests to make, you might want to consider an alternative approach. You could use a library like [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) to generate a TypeScript client. The library requires an OpenAPI definition and allows you to make requests to the Management API without having to manually write the requests yourself. The generated client will only need the token once. This can save you a lot of time and effort when working with the Management API. The Umbraco Backoffice itself is running with this library and even exports its internal HTTP client. From 05c9a9a339a5b02e0d208d40348399676d3af565 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Thu, 8 May 2025 16:29:39 +0200 Subject: [PATCH 02/65] docs: adds article on http-client --- .../foundation/fetching-data/http-client.md | 131 ++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md new file mode 100644 index 00000000000..0f36699f00e --- /dev/null +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -0,0 +1,131 @@ +--- +description: Learn more about working with the HTTP Client in Umbraco. +--- + +# HTTP Client + +Umbraco provides a built-in HTTP client that you can use to make network requests. This client is generated using **@hey-api/openapi-ts** around the OpenAPI specification and is available through the `@umbraco-cms/backoffice/http-client` package. + +```javascript +import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; + +const { data } = await umbHttpClient.get({ + url: '/umbraco/api/management/v1/server/status' +}); + +if (data) { + console.log('Server status:', data); +} +``` + +The above example shows how to use the HTTP client to make a GET request to the Management API. The `umbHttpClient` object provides methods for making requests, including `get`, `post`, `put`, and `delete`. Each method takes an options object that specifies the URL, headers, and body of the request. + +The HTTP client automatically handles authentication and error handling, so you don't have to worry about those details. It also provides a convenient way to parse the response data as JSON. + +## Executing the request + +The Backoffice also provides a `tryExecute` function that you can use to execute requests. This function will additionally wrap the request in a try/catch block and handle any errors that occur during the request. It will also show a notification if the request fails. + +```javascript +import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; +import { tryExecute } from '@umbraco-cms/backoffice/resources'; + +const { data, error } = await tryExecute(this, umbHttpClient.get({ + url: '/umbraco/api/management/v1/server/status' +})); + +if (error) { + console.error('There was a problem with the fetch operation:', error); +} else { + console.log(data); // Do something with the data +} +``` + +The `tryExecute` function takes the context of the current class or element as the first argument and the request as the second argument. Therefore, the above example can be used in any class or element that extends from either the [UmbController](https://apidocs.umbraco.com/v16/ui-api/interfaces/libs_controller-api.UmbController.html) or [UmbLitElement](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_lit-element.UmbLitElement.html) classes. + +## Custom Generated Client + +The HTTP client is generated using the [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) library. This library allows anyone to generate a TypeScript client from an OpenAPI specification. The generated client provides a convenient way to make requests to that specific API with type-safety without having to manually write the requests yourself. You can consider generating a client. This can save you a lot of time and effort when working with custom API controllers. + +If you want to generate your own client, you can use the following command: + +```bash +npm install @hey-api/openapi-ts +``` + +Then, you can use the `openapi-ts` command to generate a client from your OpenAPI specification: + +```bash +npx openapi-ts generate --url https://example.com/openapi.json --output ./my-client +``` + +This will generate a TypeScript client in the `./my-client` folder. You can then import the client into your project and use it to make requests to the Management API. + +### Connecting to the Management API + +You will need to set up a few configuration options in order to connect to the Management API. The following options are required: + +- `auth`: The authentication method to use. This is typically `Bearer` for the Management API. +- `baseUrl`: The base URL of the Management API. This is typically `https://example.com/umbraco/api/management/v1`. +- `credentials`: The credentials to use for the request. This is typically `same-origin` for the Management API. + +You can set these options either directly with the `openapi-ts` command or in a central place in your code. For example, you can create a [BackofficeEntryPoint](../../extending-overview/extension-types/backoffice-entry-point.md) that sets up the configuration options for the HTTP client: + +```javascript +import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth'; +import { client } from './my-client/client.gen'; + +export const onInit = (host) => { + host.consumeContext(UMB_AUTH_CONTEXT, async (authContext) => { + // Get the token info from Umbraco + const config = authContext?.getOpenApiConfiguration(); + + client.setConfig({ + auth: config?.token ?? undefined, + baseUrl: config?.base ?? "", + credentials: config?.credentials ?? "same-origin", + }); +}; +``` + +This will set up the HTTP client to use the Management API base URL and authentication method. You can then use the client to make requests to the Management API. + +{% hint style="info" %} +You can see the above example in action by looking at the [Umbraco Extension Template](../../development-flow/umbraco-extension-template.md). +{% endhint %} + +**Fetch API** + +The approach with a Backoffice Entry Point is good if you have a lot of requests to make. However, if you only have a few requests to make, you can use the `fetch` function directly. Read more about that here: + +{% content-ref url="fetch-api.md" %} +[fetch-api.md](fetch-api.md) +{% endcontent-ref %} + +**Setting the client directly** +You can also set the client directly in your code. This is useful if you only have a few requests to make and don't want to set up a Backoffice Entry Point. + +```javascript +import { getMyControllerAction } from './my-client'; +import { tryExecute } from '@umbraco-cms/backoffice/resources'; +import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; + +const { data } = await tryExecute(this, getMyControllerAction({ + client: umbHttpClient, +})); + +if (data) { + console.log('Server status:', data); +} +``` + +The above example shows how to use the `getMyControllerAction` function, which is generated through `openapi-ts`. The `client` parameter is the HTTP client that you want to use. You can use any HTTP client that implements the underlying interface from **@hey-api/openapi-ts**, which the Umbraco HTTP Client does. The `getMyControllerAction` function will then use the built-in HTTP client over its own to make the request to the Management API. + +## Further reading + +- [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) +- [@umbraco-cms/backoffice/http-client](https://apidocs.umbraco.com/v16/ui-api/modules/packages_core_http-client.html) +- [Using the Fetch API](fetch-api.md) +- [Working with Data](../working-with-data/README.md) +- [Creating a Backoffice API](../../../tutorials/creating-a-backoffice-api/README.md) +- [Creating a Backoffice Entry Point](../../extending-overview/extension-types/backoffice-entry-point.md) From a129be69f5b6c7399ab87c2724f2d004a518370a Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Thu, 8 May 2025 16:29:51 +0200 Subject: [PATCH 03/65] docs: adds overview and main README --- 16/umbraco-cms/SUMMARY.md | 3 +++ .../foundation/fetching-data/README.md | 15 +++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 16/umbraco-cms/customizing/foundation/fetching-data/README.md diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index 4b67e4f3a66..7563a0f9261 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -183,6 +183,9 @@ * [Extension Conditions](customizing/extending-overview/extension-conditions.md) * [Custom Extension types](customizing/extending-overview/custom-extension-type.md) * [Foundation](customizing/foundation/README.md) + * [Fetching Data](customizing/foundation/fetching-data/README.md) + * [Fetch API](customizing/foundation/fetching-data/fetch-api.md) + * [HTTP Client](customizing/foundation/fetching-data/http-client.md) * [Working with Data](customizing/foundation/working-with-data/README.md) * [Repositories](customizing/foundation/working-with-data/repositories.md) * [Context API](customizing/foundation/working-with-data/context-api.md) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md new file mode 100644 index 00000000000..2dd25e11996 --- /dev/null +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -0,0 +1,15 @@ +# Fetching Data + +Learn how to request data when extending the Backoffice. + +## [Fetch API](fetch-api.md) + +The Fetch API is a modern way to make network requests in JavaScript. It provides a more powerful and flexible feature set than the older XMLHttpRequest. + +## [HTTP Client](http-client.md) + +The HTTP Client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles things like request and response parsing, error handling, and retries. + +## [Working with Data](../working-with-data/README.md) + +Once you have the data using one of the methods above, you can read more about how to work with it here. From 5661fccad624a032287ac739e9a49a2d2ab7d86c Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Thu, 8 May 2025 16:53:54 +0200 Subject: [PATCH 04/65] docs: updates code samples after testing --- .../foundation/fetching-data/fetch-api.md | 20 +++--------- .../foundation/fetching-data/http-client.md | 32 ++++++++++++++++--- 2 files changed, 33 insertions(+), 19 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index 778fa8cdeea..159d680c7fb 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -95,7 +95,7 @@ import type { UmbClassInterface } from '@umbraco-cms/backoffice/class-api'; */ async function makeRequest(host: UmbClassInterface, url: string, method = 'GET', body?: any) { const authContext = await host.getContext(UMB_AUTH_CONTEXT); - const token = await authContext.getLatestToken(); + const token = await authContext?.getLatestToken(); const response = await fetch(url, { method, body: body ? JSON.stringify(body) : undefined, @@ -115,25 +115,15 @@ The above example serves to illustrate some of the process to make a request to Regardless of method, you can execute the fetch requests through Umbraco's [tryExecute](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_auth.UmbAuthContext.html#tryexecute) function. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again. ```javascript -import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth'; import { tryExecute } from '@umbraco-cms/backoffice/resources'; -const authContext = await this.getContext(UMB_AUTH_CONTEXT); -const token = await authContext.getLatestToken(); -const request = fetch(url, { - method, - body: body ? JSON.stringify(body) : undefined, - headers: { - 'Content-Type': 'application/json', - 'Authorization': `Bearer ${token}`, - }, -}); -const { data, error } = await tryExecute(this, request); +const request = makeRequest(this, '/umbraco/management/api/v1/server/status'); +const response = await tryExecute(this, request); -if (error) { +if (response.error) { console.error('There was a problem with the fetch operation:', error); } else { - console.log(data); // Do something with the data + console.log(response); // Do something with the data } ``` diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index 0f36699f00e..74f0e314cbb 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -10,7 +10,7 @@ Umbraco provides a built-in HTTP client that you can use to make network request import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; const { data } = await umbHttpClient.get({ - url: '/umbraco/api/management/v1/server/status' + url: '/umbraco/management/api/v1/server/status' }); if (data) { @@ -31,7 +31,7 @@ import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; import { tryExecute } from '@umbraco-cms/backoffice/resources'; const { data, error } = await tryExecute(this, umbHttpClient.get({ - url: '/umbraco/api/management/v1/server/status' + url: '/umbraco/management/api/v1/server/status' })); if (error) { @@ -43,6 +43,30 @@ if (error) { The `tryExecute` function takes the context of the current class or element as the first argument and the request as the second argument. Therefore, the above example can be used in any class or element that extends from either the [UmbController](https://apidocs.umbraco.com/v16/ui-api/interfaces/libs_controller-api.UmbController.html) or [UmbLitElement](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_lit-element.UmbLitElement.html) classes. +It is recommended to use the `tryExecute` function instead of the raw HTTP client. It can also be configured not to show notifications, if you want to handle errors yourself: + +```javascript +tryExecute(this, request, { + disableNotifications: true, +}); +``` + +### Cancelling requests + +The HTTP client also supports cancelling requests. This is useful if you want to cancel a request that is taking too long or if the user navigates away from the page. You can cancel a request by using the [AbortController API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController). The `AbortController` API is a built-in API in modern browsers that allows you to cancel requests. You can use it directly with tryExecute: + +```javascript +const abortController = new AbortController(); + +// Cancel the request before starting it for illustration purposes +abortController.abort(); + +tryExecute(this, request, { + disableNotifications: true, + abortSignal: abortController.signal, +}); +``` + ## Custom Generated Client The HTTP client is generated using the [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) library. This library allows anyone to generate a TypeScript client from an OpenAPI specification. The generated client provides a convenient way to make requests to that specific API with type-safety without having to manually write the requests yourself. You can consider generating a client. This can save you a lot of time and effort when working with custom API controllers. @@ -76,7 +100,7 @@ import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth'; import { client } from './my-client/client.gen'; export const onInit = (host) => { - host.consumeContext(UMB_AUTH_CONTEXT, async (authContext) => { + host.consumeContext(UMB_AUTH_CONTEXT, (authContext) => { // Get the token info from Umbraco const config = authContext?.getOpenApiConfiguration(); @@ -111,7 +135,7 @@ import { tryExecute } from '@umbraco-cms/backoffice/resources'; import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; const { data } = await tryExecute(this, getMyControllerAction({ - client: umbHttpClient, + client: umbHttpClient, // Use Umbraco's HTTP client })); if (data) { From 20a72e7f543b2c4c4ababae33de1898971d5a29d Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Thu, 8 May 2025 16:57:22 +0200 Subject: [PATCH 05/65] docs: corrects wrong variable use --- .../customizing/foundation/fetching-data/fetch-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index 159d680c7fb..364fb576871 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -121,7 +121,7 @@ const request = makeRequest(this, '/umbraco/management/api/v1/server/status'); const response = await tryExecute(this, request); if (response.error) { - console.error('There was a problem with the fetch operation:', error); + console.error('There was a problem with the fetch operation:', response.error); } else { console.log(response); // Do something with the data } From 2154db3bea56181b2d039f7bac60541cbb13f508 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 11:17:18 +0200 Subject: [PATCH 06/65] docs: adds an article on how to execute requests this also merges part information found in other articles --- 16/umbraco-cms/SUMMARY.md | 1 + .../foundation/fetching-data/fetch-api.md | 12 ++-- .../foundation/fetching-data/http-client.md | 45 ++----------- .../foundation/fetching-data/try-execute.md | 64 +++++++++++++++++++ 4 files changed, 80 insertions(+), 42 deletions(-) create mode 100644 16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index 7563a0f9261..2bd5c7d033a 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -186,6 +186,7 @@ * [Fetching Data](customizing/foundation/fetching-data/README.md) * [Fetch API](customizing/foundation/fetching-data/fetch-api.md) * [HTTP Client](customizing/foundation/fetching-data/http-client.md) + * [Executing Requests](customizing/foundation/fetching-data/try-execute.md) * [Working with Data](customizing/foundation/working-with-data/README.md) * [Repositories](customizing/foundation/working-with-data/repositories.md) * [Context API](customizing/foundation/working-with-data/context-api.md) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index 364fb576871..febff0466e2 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -114,6 +114,8 @@ The above example serves to illustrate some of the process to make a request to Regardless of method, you can execute the fetch requests through Umbraco's [tryExecute](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_auth.UmbAuthContext.html#tryexecute) function. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again. +**Example:** + ```javascript import { tryExecute } from '@umbraco-cms/backoffice/resources'; @@ -127,12 +129,14 @@ if (response.error) { } ``` -{% hint style="info" %} -The above example requires a host element illustrated by the use of `this`. This is typically a custom element that extends the `UmbLitElement` class. -{% endhint %} +You can read more about the `tryExecute` function in this article: + +{% content-ref url="../try-execute.md" %} +[try-execute.md](../try-execute.md) +{% endcontent-ref %} ## Conclusion The Fetch API is a powerful and flexible way to make network requests in JavaScript. It is available in all modern browsers and is the recommended way to make network requests in JavaScript. The Fetch API can be used in Umbraco to make network requests to the server. It can also be used to make requests to the Management API controllers. You can use the Fetch API to make requests to any endpoint in the Management API. You can also use it to handle responses in a variety of formats. This is especially useful, if you have but a few requests to make. -However, if you have a lot of requests to make, you might want to consider an alternative approach. You could use a library like [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) to generate a TypeScript client. The library requires an OpenAPI definition and allows you to make requests to the Management API without having to manually write the requests yourself. The generated client will only need the token once. This can save you a lot of time and effort when working with the Management API. The Umbraco Backoffice itself is running with this library and even exports its internal HTTP client. +However, if you have a lot of requests to make, you might want to consider an alternative approach. You could use a library like [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) to generate a TypeScript client. The library requires an OpenAPI definition and allows you to make requests to the Management API without having to manually write the requests yourself. The generated client will only need the token once. This can save you a lot of time and effort when working with the Management API. The Umbraco Backoffice itself is running with this library and even exports its internal HTTP client. You can read more about this in the [HTTP Client](http-client.md) article. diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index 74f0e314cbb..e8378be0517 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -22,50 +22,19 @@ The above example shows how to use the HTTP client to make a GET request to the The HTTP client automatically handles authentication and error handling, so you don't have to worry about those details. It also provides a convenient way to parse the response data as JSON. -## Executing the request +## Using the HTTP Client -The Backoffice also provides a `tryExecute` function that you can use to execute requests. This function will additionally wrap the request in a try/catch block and handle any errors that occur during the request. It will also show a notification if the request fails. +The HTTP client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles things like request and response parsing, error handling, and retries. The HTTP client is available through the `@umbraco-cms/backoffice/http-client` package, which is included in the Umbraco Backoffice. You can use it to make requests to any endpoint in the Management API or to any other API. -```javascript -import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; -import { tryExecute } from '@umbraco-cms/backoffice/resources'; - -const { data, error } = await tryExecute(this, umbHttpClient.get({ - url: '/umbraco/management/api/v1/server/status' -})); +The recommended approach to use the Umbraco HTTP Client is to use the `tryExecute` function. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again. -if (error) { - console.error('There was a problem with the fetch operation:', error); -} else { - console.log(data); // Do something with the data -} -``` - -The `tryExecute` function takes the context of the current class or element as the first argument and the request as the second argument. Therefore, the above example can be used in any class or element that extends from either the [UmbController](https://apidocs.umbraco.com/v16/ui-api/interfaces/libs_controller-api.UmbController.html) or [UmbLitElement](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_lit-element.UmbLitElement.html) classes. +You can read more about the `tryExecute` function in this article: -It is recommended to use the `tryExecute` function instead of the raw HTTP client. It can also be configured not to show notifications, if you want to handle errors yourself: - -```javascript -tryExecute(this, request, { - disableNotifications: true, -}); -``` - -### Cancelling requests - -The HTTP client also supports cancelling requests. This is useful if you want to cancel a request that is taking too long or if the user navigates away from the page. You can cancel a request by using the [AbortController API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController). The `AbortController` API is a built-in API in modern browsers that allows you to cancel requests. You can use it directly with tryExecute: +{% content-ref url="../try-execute.md" %} +[try-execute.md](../try-execute.md) +{% endcontent-ref %} ```javascript -const abortController = new AbortController(); - -// Cancel the request before starting it for illustration purposes -abortController.abort(); - -tryExecute(this, request, { - disableNotifications: true, - abortSignal: abortController.signal, -}); -``` ## Custom Generated Client diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md new file mode 100644 index 00000000000..67d1742fa53 --- /dev/null +++ b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md @@ -0,0 +1,64 @@ +--- +description:: Learn how to execute requests in the Backoffice. +--- + +# Executing Requests + +When you make a request to the server, you need to execute it. This can be done using the Fetch API or the Umbraco HTTP client. The Backoffice also provides a `tryExecute` function that you can use to execute requests. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again. + +{% hint style="info" %} +You can read the technical documentation for the `tryExecute` function in the [UI API Documentation](https://apidocs.umbraco.com/v16/ui-api/functions/packages_core_resources.tryExecute.html) class. +{% endhint %} + +## Using the HTTP Client + +Here is an example of how to use the `tryExecute` function with the Umbraco HTTP client: + +```javascript +import { tryExecute } from '@umbraco-cms/backoffice/resources'; +import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; + +const { data, error } = await tryExecute(this, umbHttpClient.get({ + url: '/umbraco/management/api/v1/server/status' +})); + +if (error) { + console.error('There was a problem with the fetch operation:', error); +} else { + console.log(data); // Do something with the data +} +``` + +The `tryExecute` function takes the context of the current class or element as the first argument and the request as the second argument. Therefore, the above example can be used in any class or element that extends from either the [UmbController](https://apidocs.umbraco.com/v16/ui-api/interfaces/libs_controller-api.UmbController.html) or [UmbLitElement](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_lit-element.UmbLitElement.html) classes. + +{% hint style="info" %} +The above example requires a host element illustrated by the use of `this`. This is typically a custom element that extends the `UmbLitElement` class. +{% endhint %} + +It is recommended to always use the `tryExecute` function to wrap HTTP requests. + +### Disable Notifications + +The `tryExecute` function will automatically show error bubbles if a request fails. There may be valid cases where you want handle errors yourself. This could for instance be if you want to show a custom error message. You can disable the notifications by passing the `disableNotifications` option to the `tryExecute` function: + +```javascript +tryExecute(this, request, { + disableNotifications: true, +}); +``` + +### Cancelling requests + +The `tryExecute` function also supports cancelling requests. This is useful if you want to cancel a request that is taking too long or if the user navigates away from the page. You can cancel a request by using the [AbortController API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController). The `AbortController` API is a built-in API in modern browsers that allows you to cancel requests. You can use it directly with tryExecute: + +```javascript +const abortController = new AbortController(); + +// Cancel the request before starting it for illustration purposes +abortController.abort(); + +tryExecute(this, request, { + disableNotifications: true, + abortSignal: abortController.signal, +}); +``` From bf640935cd60a62208013fd2ef12d285f8404d11 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 11:17:43 +0200 Subject: [PATCH 07/65] docs: adds reference to new article --- .../foundation/fetching-data/README.md | 30 +++++++++++++++++-- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 2dd25e11996..8f87082f8f5 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -1,15 +1,39 @@ +--- +description: Learn how to request data when extending the Backoffice. +--- + # Fetching Data -Learn how to request data when extending the Backoffice. +## Fetch Data Through HTTP + +There are two main ways to fetch data through HTTP in the Umbraco Backoffice: using the Fetch API or the Umbraco HTTP client. The Fetch API is a modern way to make network requests in JavaScript, while the Umbraco HTTP client is a wrapper around the Fetch API. That provides a more convenient way to make network requests. + +For most scenarios, we recommend using the Umbraco HTTP client provided by Umbraco. The Fetch API is an alternative for simpler use cases. Here is a quick overview of the two options for you to compare: + + | Feature | [Fetch API](fetch-api.md) | [Umbraco HTTP Client](http-client.md) | +|------------------------|-------------------------------|------------------------------| +| Authentication | Manual | Automatic | +| Error Handling | Manual | Built-in | +| Type Safety | No | Yes | +| Request Cancellation | Yes (via AbortController) | Yes (via AbortController) | +| Recommended Use Case | Standard requests | Complex or frequent requests| -## [Fetch API](fetch-api.md) +Once you have decided which option to use, you can read more about how to use it below. After that, you can read about how to work with the data you receive from the server. + +### [Fetch API](fetch-api.md) The Fetch API is a modern way to make network requests in JavaScript. It provides a more powerful and flexible feature set than the older XMLHttpRequest. -## [HTTP Client](http-client.md) +### [HTTP Client](http-client.md) The HTTP Client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles things like request and response parsing, error handling, and retries. +## Handle Requests + +### [Executing Requests](try-execute.md) + +Executing the request is the next step after fetching data. You can use the `tryExecute` function to handle errors and refresh the token if it is expired. + ## [Working with Data](../working-with-data/README.md) Once you have the data using one of the methods above, you can read more about how to work with it here. From 5d7e9754e0e6503517053178a2db6de9e7b2eea8 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 11:17:51 +0200 Subject: [PATCH 08/65] docs: removes warning --- .../customizing/foundation/working-with-data/README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/working-with-data/README.md b/16/umbraco-cms/customizing/foundation/working-with-data/README.md index bff06641049..ee3ed8c1093 100644 --- a/16/umbraco-cms/customizing/foundation/working-with-data/README.md +++ b/16/umbraco-cms/customizing/foundation/working-with-data/README.md @@ -2,10 +2,6 @@ Learn how to work with data or request the data when extending the backoffice. -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - ## [Repositories](repositories.md) Repositories are used for talking to the server by requesting data and getting notified about updates. From 590dfe5ca32082731a38a2b3edc9ff9d202b3651 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 11:23:56 +0200 Subject: [PATCH 09/65] docs: adds an article on generating your own custom client --- 16/umbraco-cms/SUMMARY.md | 1 + .../foundation/fetching-data/README.md | 8 +- .../fetching-data/custom-generated-client.md | 92 +++++++++++++++++++ .../foundation/fetching-data/http-client.md | 81 +--------------- 4 files changed, 105 insertions(+), 77 deletions(-) create mode 100644 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index 2bd5c7d033a..4202053de6e 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -187,6 +187,7 @@ * [Fetch API](customizing/foundation/fetching-data/fetch-api.md) * [HTTP Client](customizing/foundation/fetching-data/http-client.md) * [Executing Requests](customizing/foundation/fetching-data/try-execute.md) + * [Custom Generated Client](customizing/foundation/fetching-data/custom-generated-client.md) * [Working with Data](customizing/foundation/working-with-data/README.md) * [Repositories](customizing/foundation/working-with-data/repositories.md) * [Context API](customizing/foundation/working-with-data/context-api.md) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 8f87082f8f5..4063b1f3017 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -34,6 +34,12 @@ The HTTP Client is a wrapper around the Fetch API that provides a more convenien Executing the request is the next step after fetching data. You can use the `tryExecute` function to handle errors and refresh the token if it is expired. -## [Working with Data](../working-with-data/README.md) +### [Custom Generated Client](custom-generated-client.md) + +It can be useful to generate a custom client for your API. This can save you a lot of time and effort when working with custom API controllers. + +## Further Reading + +### [Working with Data](../working-with-data/README.md) Once you have the data using one of the methods above, you can read more about how to work with it here. diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md new file mode 100644 index 00000000000..a09024af082 --- /dev/null +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -0,0 +1,92 @@ +--- +description: Learn how to create a custom generated client with TypeScript types for your OpenAPI specification. +--- + +# Custom Generated Client + +The Umbraco Backoffice provides a built-in HTTP client that you can use to make network requests. This client is generated using **@hey-api/openapi-ts** around the OpenAPI specification and is available through the `@umbraco-cms/backoffice/http-client` package. + +{% content-ref url="http-client.md" %} +[http-client.md](http-client.md) +{% endcontent-ref %} + +The HTTP client is generated using the [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) library. This library allows anyone to generate a TypeScript client from an OpenAPI specification. The generated client provides a convenient way to make requests to that specific API with type-safety without having to manually write the requests yourself. You can consider generating a client. This can save you a lot of time and effort when working with custom API controllers. + +If you want to generate your own client, you can use the following command: + +```bash +npm install @hey-api/openapi-ts +``` + +Then, you can use the `openapi-ts` command to generate a client from your OpenAPI specification: + +```bash +npx openapi-ts generate --url https://example.com/openapi.json --output ./my-client +``` + +This will generate a TypeScript client in the `./my-client` folder. You can then import the client into your project and use it to make requests to the Management API. + +### Connecting to the Management API + +You will need to set up a few configuration options in order to connect to the Management API. The following options are required: + +- `auth`: The authentication method to use. This is typically `Bearer` for the Management API. +- `baseUrl`: The base URL of the Management API. This is typically `https://example.com/umbraco/api/management/v1`. +- `credentials`: The credentials to use for the request. This is typically `same-origin` for the Management API. + +You can set these options either directly with the `openapi-ts` command or in a central place in your code. For example, you can create a [BackofficeEntryPoint](../../extending-overview/extension-types/backoffice-entry-point.md) that sets up the configuration options for the HTTP client: + +```javascript +import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth'; +import { client } from './my-client/client.gen'; + +export const onInit = (host) => { + host.consumeContext(UMB_AUTH_CONTEXT, (authContext) => { + // Get the token info from Umbraco + const config = authContext?.getOpenApiConfiguration(); + + client.setConfig({ + auth: config?.token ?? undefined, + baseUrl: config?.base ?? "", + credentials: config?.credentials ?? "same-origin", + }); +}; +``` + +This will set up the HTTP client to use the Management API base URL and authentication method. You can then use the client to make requests to the Management API. + +{% hint style="info" %} +You can see the above example in action by looking at the [Umbraco Extension Template](../../development-flow/umbraco-extension-template.md). +{% endhint %} + +**Fetch API** + +The approach with a Backoffice Entry Point is good if you have a lot of requests to make. However, if you only have a few requests to make, you can use the `fetch` function directly. Read more about that here: + +{% content-ref url="fetch-api.md" %} +[fetch-api.md](fetch-api.md) +{% endcontent-ref %} + +**Setting the client directly** +You can also set the client directly in your code. This is useful if you only have a few requests to make and don't want to set up a Backoffice Entry Point. + +```javascript +import { getMyControllerAction } from './my-client'; +import { tryExecute } from '@umbraco-cms/backoffice/resources'; +import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; + +const { data } = await tryExecute(this, getMyControllerAction({ + client: umbHttpClient, // Use Umbraco's HTTP client +})); + +if (data) { + console.log('Server status:', data); +} +``` + +The above example shows how to use the `getMyControllerAction` function, which is generated through `openapi-ts`. The `client` parameter is the HTTP client that you want to use. You can use any HTTP client that implements the underlying interface from **@hey-api/openapi-ts**, which the Umbraco HTTP Client does. The `getMyControllerAction` function will then use the built-in HTTP client over its own to make the request to the Management API. + +## Further reading + +- [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) +- [Creating a Backoffice API](../../../tutorials/creating-a-backoffice-api/README.md) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index e8378be0517..98e55024f99 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -34,91 +34,20 @@ You can read more about the `tryExecute` function in this article: [try-execute.md](../try-execute.md) {% endcontent-ref %} -```javascript - -## Custom Generated Client - -The HTTP client is generated using the [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) library. This library allows anyone to generate a TypeScript client from an OpenAPI specification. The generated client provides a convenient way to make requests to that specific API with type-safety without having to manually write the requests yourself. You can consider generating a client. This can save you a lot of time and effort when working with custom API controllers. - -If you want to generate your own client, you can use the following command: +## Generate your own client -```bash -npm install @hey-api/openapi-ts -``` - -Then, you can use the `openapi-ts` command to generate a client from your OpenAPI specification: - -```bash -npx openapi-ts generate --url https://example.com/openapi.json --output ./my-client -``` +You can also generate your own client using the **@hey-api/openapi-ts** library. This library allows you to generate a TypeScript client from an OpenAPI specification. The generated client will handle authentication and error handling for you, so you don't have to worry about those details. -This will generate a TypeScript client in the `./my-client` folder. You can then import the client into your project and use it to make requests to the Management API. - -### Connecting to the Management API - -You will need to set up a few configuration options in order to connect to the Management API. The following options are required: - -- `auth`: The authentication method to use. This is typically `Bearer` for the Management API. -- `baseUrl`: The base URL of the Management API. This is typically `https://example.com/umbraco/api/management/v1`. -- `credentials`: The credentials to use for the request. This is typically `same-origin` for the Management API. - -You can set these options either directly with the `openapi-ts` command or in a central place in your code. For example, you can create a [BackofficeEntryPoint](../../extending-overview/extension-types/backoffice-entry-point.md) that sets up the configuration options for the HTTP client: - -```javascript -import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth'; -import { client } from './my-client/client.gen'; - -export const onInit = (host) => { - host.consumeContext(UMB_AUTH_CONTEXT, (authContext) => { - // Get the token info from Umbraco - const config = authContext?.getOpenApiConfiguration(); - - client.setConfig({ - auth: config?.token ?? undefined, - baseUrl: config?.base ?? "", - credentials: config?.credentials ?? "same-origin", - }); -}; -``` +Read more about generating your own client here: -This will set up the HTTP client to use the Management API base URL and authentication method. You can then use the client to make requests to the Management API. - -{% hint style="info" %} -You can see the above example in action by looking at the [Umbraco Extension Template](../../development-flow/umbraco-extension-template.md). -{% endhint %} - -**Fetch API** - -The approach with a Backoffice Entry Point is good if you have a lot of requests to make. However, if you only have a few requests to make, you can use the `fetch` function directly. Read more about that here: - -{% content-ref url="fetch-api.md" %} -[fetch-api.md](fetch-api.md) +{% content-ref url="custom-generated-client.md" %} +[custom-generated-client.md](custom-generated-client.md) {% endcontent-ref %} -**Setting the client directly** -You can also set the client directly in your code. This is useful if you only have a few requests to make and don't want to set up a Backoffice Entry Point. - -```javascript -import { getMyControllerAction } from './my-client'; -import { tryExecute } from '@umbraco-cms/backoffice/resources'; -import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; - -const { data } = await tryExecute(this, getMyControllerAction({ - client: umbHttpClient, // Use Umbraco's HTTP client -})); - -if (data) { - console.log('Server status:', data); -} -``` - -The above example shows how to use the `getMyControllerAction` function, which is generated through `openapi-ts`. The `client` parameter is the HTTP client that you want to use. You can use any HTTP client that implements the underlying interface from **@hey-api/openapi-ts**, which the Umbraco HTTP Client does. The `getMyControllerAction` function will then use the built-in HTTP client over its own to make the request to the Management API. - ## Further reading - [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) - [@umbraco-cms/backoffice/http-client](https://apidocs.umbraco.com/v16/ui-api/modules/packages_core_http-client.html) - [Using the Fetch API](fetch-api.md) - [Working with Data](../working-with-data/README.md) -- [Creating a Backoffice API](../../../tutorials/creating-a-backoffice-api/README.md) - [Creating a Backoffice Entry Point](../../extending-overview/extension-types/backoffice-entry-point.md) From 1b2687db5d57abe59eda9da16557e65ea9c475fb Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 11:29:38 +0200 Subject: [PATCH 10/65] docs: adds bullets to why to choose the http-client --- .../customizing/foundation/fetching-data/README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 4063b1f3017..65c1ecac070 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -8,7 +8,15 @@ description: Learn how to request data when extending the Backoffice. There are two main ways to fetch data through HTTP in the Umbraco Backoffice: using the Fetch API or the Umbraco HTTP client. The Fetch API is a modern way to make network requests in JavaScript, while the Umbraco HTTP client is a wrapper around the Fetch API. That provides a more convenient way to make network requests. -For most scenarios, we recommend using the Umbraco HTTP client provided by Umbraco. The Fetch API is an alternative for simpler use cases. Here is a quick overview of the two options for you to compare: +For most scenarios, we recommend using the Umbraco HTTP Client because it: + +- Automatically handles authentication and error handling. +- Provides type safety for requests and responses. +- Simplifies request and response parsing. + +The Fetch API is an alternative for simpler use cases. + +Here is a quick overview of the two options for you to compare: | Feature | [Fetch API](fetch-api.md) | [Umbraco HTTP Client](http-client.md) | |------------------------|-------------------------------|------------------------------| From dd9ce4a1ab1a1d1e12f8e6613e332029f440f1af Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 12:04:21 +0200 Subject: [PATCH 11/65] docs: name the client the same --- .../foundation/fetching-data/custom-generated-client.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index a09024af082..1c340d3e908 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -4,7 +4,7 @@ description: Learn how to create a custom generated client with TypeScript types # Custom Generated Client -The Umbraco Backoffice provides a built-in HTTP client that you can use to make network requests. This client is generated using **@hey-api/openapi-ts** around the OpenAPI specification and is available through the `@umbraco-cms/backoffice/http-client` package. +The Umbraco Backoffice provides a built-in HTTP client that you can use to make network requests. This client is colloquially known as the Umbraco HTTP Client. It is generated using **@hey-api/openapi-ts** around the OpenAPI specification and is available through the `@umbraco-cms/backoffice/http-client` package. {% content-ref url="http-client.md" %} [http-client.md](http-client.md) @@ -84,7 +84,7 @@ if (data) { } ``` -The above example shows how to use the `getMyControllerAction` function, which is generated through `openapi-ts`. The `client` parameter is the HTTP client that you want to use. You can use any HTTP client that implements the underlying interface from **@hey-api/openapi-ts**, which the Umbraco HTTP Client does. The `getMyControllerAction` function will then use the built-in HTTP client over its own to make the request to the Management API. +The above example shows how to use the `getMyControllerAction` function, which is generated through `openapi-ts`. The `client` parameter is the HTTP client that you want to use. You can use any HTTP client that implements the underlying interface from **@hey-api/openapi-ts**, which the Umbraco HTTP Client does. The `getMyControllerAction` function will then use the Umbraco HTTP client over its own to make the request to the Management API. ## Further reading From ae00ae66916dcc4ab91b944fed1c7d7e6155af0a Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 12:10:09 +0200 Subject: [PATCH 12/65] docs: clarify what a custom client is --- .../fetching-data/custom-generated-client.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 1c340d3e908..b4a50da8ca7 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -4,15 +4,19 @@ description: Learn how to create a custom generated client with TypeScript types # Custom Generated Client -The Umbraco Backoffice provides a built-in HTTP client that you can use to make network requests. This client is colloquially known as the Umbraco HTTP Client. It is generated using **@hey-api/openapi-ts** around the OpenAPI specification and is available through the `@umbraco-cms/backoffice/http-client` package. +Umbraco uses [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) to generate its HTTP client for the OpenAPI specification of the Management API. It is available through the `@umbraco-cms/backoffice/http-client` package. {% content-ref url="http-client.md" %} [http-client.md](http-client.md) {% endcontent-ref %} -The HTTP client is generated using the [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) library. This library allows anyone to generate a TypeScript client from an OpenAPI specification. The generated client provides a convenient way to make requests to that specific API with type-safety without having to manually write the requests yourself. You can consider generating a client. This can save you a lot of time and effort when working with custom API controllers. +The following examples will show you how to generate a client from an OpenAPI specification and how to use it in your project. We use the **@hey-api/openapi-ts** library, but the same principles apply to any other library that generates a TypeScript client. -If you want to generate your own client, you can use the following command: +## Generate your own client + +The generated client provides a convenient way to make requests to that specific API with type-safety without having to manually write the requests yourself. You can consider generating a client. This can save you a lot of time and effort when working with custom API controllers. + +To get started, you can install the generator using the following command: ```bash npm install @hey-api/openapi-ts @@ -26,7 +30,7 @@ npx openapi-ts generate --url https://example.com/openapi.json --output ./my-cli This will generate a TypeScript client in the `./my-client` folder. You can then import the client into your project and use it to make requests to the Management API. -### Connecting to the Management API +## Connecting to the Management API You will need to set up a few configuration options in order to connect to the Management API. The following options are required: From dc0ad3883c09ea33c480d1ffaba4e2bd15d58479 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 12:10:20 +0200 Subject: [PATCH 13/65] docs: clarify what the umbraco http client is --- .../customizing/foundation/fetching-data/http-client.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index 98e55024f99..66d1ce94a70 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -4,7 +4,9 @@ description: Learn more about working with the HTTP Client in Umbraco. # HTTP Client -Umbraco provides a built-in HTTP client that you can use to make network requests. This client is generated using **@hey-api/openapi-ts** around the OpenAPI specification and is available through the `@umbraco-cms/backoffice/http-client` package. +The Umbraco Backoffice provides a built-in HTTP client that you can use to make network requests. This client is colloquially known as the Umbraco HTTP Client. It is generated using **@hey-api/openapi-ts** around the OpenAPI specification and is available through the `@umbraco-cms/backoffice/http-client` package. + +**Example:** ```javascript import { umbHttpClient } from '@umbraco-cms/backoffice/http-client'; From a5177c567b4957c6ba5e2aac154d9e8b8e218f52 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 12:11:38 +0200 Subject: [PATCH 14/65] docs: adds an advanced topics section --- 16/umbraco-cms/customizing/foundation/fetching-data/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 65c1ecac070..46d52b26bc4 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -38,10 +38,12 @@ The HTTP Client is a wrapper around the Fetch API that provides a more convenien ## Handle Requests -### [Executing Requests](try-execute.md) +## [Executing Requests](try-execute.md) Executing the request is the next step after fetching data. You can use the `tryExecute` function to handle errors and refresh the token if it is expired. +## Advanced Topics + ### [Custom Generated Client](custom-generated-client.md) It can be useful to generate a custom client for your API. This can save you a lot of time and effort when working with custom API controllers. From f90e7c78fce4a50faa648fe96594b0facf9cd616 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 13:08:38 +0200 Subject: [PATCH 15/65] docs: adds examples on authentication --- .../foundation/fetching-data/fetch-api.md | 51 ++++++++++++++++--- 1 file changed, 43 insertions(+), 8 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index febff0466e2..f59dc363398 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -40,23 +40,58 @@ The example assumes that you have a controller set up at the `/umbraco/MyApiCont When making requests to the Umbraco API controllers, you may need to include an authorization token in the request headers. This is especially important when making requests to endpoints that require authentication. -The Fetch API does not automatically include authentication tokens in requests. You need to manually add the authentication token to the request headers. This can be done by adding an `Authorization` header to the request: +The Fetch API does not automatically include authentication tokens in requests. You need to manually add the authentication token to the request headers. While you can manage tokens manually, the recommended approach in the Backoffice is to use the **UMB_AUTH_CONTEXT**. This context provides tools to manage authentication tokens and ensures that your requests are properly authenticated. + +### Example: Using `UMB_AUTH_CONTEXT` for Authentication + +The following example demonstrates how to use `UMB_AUTH_CONTEXT` to retrieve the latest token and make an authenticated request: ```javascript -const token = 'your-auth-token'; -const data = await fetch('/umbraco/MyApiController/GetData', { - method: 'GET', +import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth'; +import type { UmbClassInterface } from '@umbraco-cms/backoffice/class-api'; + +async function fetchData(host: UmbClassInterface, endpoint: string) { + // Retrieve the authentication context + const authContext = await host.getContext(UMB_AUTH_CONTEXT); + + // Get the latest token + const token = await authContext?.getLatestToken(); + + // Make the authenticated request + const response = await fetch(endpoint, { + method: 'GET', headers: { - 'Authorization': `Bearer ${token}`, - 'Content-Type': 'application/json' - } -}); + 'Authorization': `Bearer ${token}`, + 'Content-Type': 'application/json', + }, + }); + + if (!response.ok) { + throw new Error('Failed to fetch data'); + } + + return response.json(); +} + +// Example usage +const data = await fetchData(this, '/umbraco/management/api/v1/server/status'); +console.log(data); ``` {% hint style="info" %} The example assumes that you have a valid authentication token. You can replace this with your own token as needed. Read more about authentication in the [Security](../../../implementation/security.md) article. {% endhint %} +Why Use **UMB_AUTH_CONTEXT**? + +- Simplifies Token Management: Automatically retrieves and refreshes tokens when needed. +- Aligns with Best Practices: Ensures your requests are authenticated in a way that integrates seamlessly with the Backoffice. +- Reduces Errors: Avoids common pitfalls like expired tokens or incorrect headers. + +{% hint style="info" %} +The **UMB_AUTH_CONTEXT** is only available in the Backoffice. For external applications, you will need to manage tokens manually or use an API user. Read more about API users in the [API Users article](../../../fundamentals/data/users/api-users.md). +{% endhint %} + ## Management API Controllers The Fetch API can also be used to make requests to the Management API controllers. The Management API is a set of RESTful APIs that allow you to interact with Umbraco programmatically. You can use the Fetch API to make requests to the Management API controllers like you would with any other API. The Management API controllers are located in the `/umbraco/api/management` namespace. You can use the Fetch API to make requests to these controllers like you would with any other API. From 1ad9cee3bae0dc28489350f2d24ec4e395bc2a49 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 13:10:38 +0200 Subject: [PATCH 16/65] docs: adds extra bullet --- 16/umbraco-cms/customizing/foundation/fetching-data/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 46d52b26bc4..41cf6487cb1 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -13,6 +13,7 @@ For most scenarios, we recommend using the Umbraco HTTP Client because it: - Automatically handles authentication and error handling. - Provides type safety for requests and responses. - Simplifies request and response parsing. +- Integrates seamlessly with the Backoffice. The Fetch API is an alternative for simpler use cases. From 0666e56d1049cdb248f2dfef02ab89aabb344485 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 13:12:36 +0200 Subject: [PATCH 17/65] docs: align naming of http client --- 16/umbraco-cms/SUMMARY.md | 2 +- .../customizing/foundation/fetching-data/README.md | 4 ++-- .../foundation/fetching-data/http-client.md | 10 +++++----- .../foundation/fetching-data/try-execute.md | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index 4202053de6e..644240cc184 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -185,7 +185,7 @@ * [Foundation](customizing/foundation/README.md) * [Fetching Data](customizing/foundation/fetching-data/README.md) * [Fetch API](customizing/foundation/fetching-data/fetch-api.md) - * [HTTP Client](customizing/foundation/fetching-data/http-client.md) + * [Umbraco HTTP Client](customizing/foundation/fetching-data/http-client.md) * [Executing Requests](customizing/foundation/fetching-data/try-execute.md) * [Custom Generated Client](customizing/foundation/fetching-data/custom-generated-client.md) * [Working with Data](customizing/foundation/working-with-data/README.md) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 41cf6487cb1..658d6b5448d 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -33,9 +33,9 @@ Once you have decided which option to use, you can read more about how to use it The Fetch API is a modern way to make network requests in JavaScript. It provides a more powerful and flexible feature set than the older XMLHttpRequest. -### [HTTP Client](http-client.md) +### [Umbraco HTTP Client](http-client.md) -The HTTP Client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles things like request and response parsing, error handling, and retries. +The Umbraco HTTP Client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles things like request and response parsing, error handling, and retries. ## Handle Requests diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index 66d1ce94a70..d2c2ff7a290 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -1,5 +1,5 @@ --- -description: Learn more about working with the HTTP Client in Umbraco. +description: Learn more about working with the Umbraco HTTP Client. --- # HTTP Client @@ -20,13 +20,13 @@ if (data) { } ``` -The above example shows how to use the HTTP client to make a GET request to the Management API. The `umbHttpClient` object provides methods for making requests, including `get`, `post`, `put`, and `delete`. Each method takes an options object that specifies the URL, headers, and body of the request. +The above example shows how to use the Umbraco HTTP client to make a GET request to the Management API. The `umbHttpClient` object provides methods for making requests, including `get`, `post`, `put`, and `delete`. Each method takes an options object that specifies the URL, headers, and body of the request. -The HTTP client automatically handles authentication and error handling, so you don't have to worry about those details. It also provides a convenient way to parse the response data as JSON. +The Umbraco HTTP client automatically handles authentication and error handling, so you don't have to worry about those details. It also provides a convenient way to parse the response data as JSON. -## Using the HTTP Client +## Using the Umbraco HTTP Client -The HTTP client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles things like request and response parsing, error handling, and retries. The HTTP client is available through the `@umbraco-cms/backoffice/http-client` package, which is included in the Umbraco Backoffice. You can use it to make requests to any endpoint in the Management API or to any other API. +The Umbraco HTTP client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles things like request and response parsing, error handling, and retries. The Umbraco HTTP client is available through the `@umbraco-cms/backoffice/http-client` package, which is included in the Umbraco Backoffice. You can use it to make requests to any endpoint in the Management API or to any other API. The recommended approach to use the Umbraco HTTP Client is to use the `tryExecute` function. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again. diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md index 67d1742fa53..60878cd2459 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md @@ -10,7 +10,7 @@ When you make a request to the server, you need to execute it. This can be done You can read the technical documentation for the `tryExecute` function in the [UI API Documentation](https://apidocs.umbraco.com/v16/ui-api/functions/packages_core_resources.tryExecute.html) class. {% endhint %} -## Using the HTTP Client +## Using the Umbraco HTTP Client Here is an example of how to use the `tryExecute` function with the Umbraco HTTP client: From d4a4236ed17300fa633f962d82b7d7d41ab2693d Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 13:13:41 +0200 Subject: [PATCH 18/65] docs: simplify example --- .../customizing/foundation/fetching-data/fetch-api.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index f59dc363398..b08e1ee108a 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -48,18 +48,12 @@ The following example demonstrates how to use `UMB_AUTH_CONTEXT` to retrieve the ```javascript import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth'; -import type { UmbClassInterface } from '@umbraco-cms/backoffice/class-api'; -async function fetchData(host: UmbClassInterface, endpoint: string) { - // Retrieve the authentication context +async function fetchData(host, endpoint) { const authContext = await host.getContext(UMB_AUTH_CONTEXT); - - // Get the latest token const token = await authContext?.getLatestToken(); - // Make the authenticated request const response = await fetch(endpoint, { - method: 'GET', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json', From d3e6d163414527385a9f3ae1d95675f8838a21f3 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 13:14:39 +0200 Subject: [PATCH 19/65] docs: adds warning about error handling --- .../customizing/foundation/fetching-data/fetch-api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index b08e1ee108a..25857996c67 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -36,6 +36,10 @@ if (data) { The example assumes that you have a controller set up at the `/umbraco/MyApiController/GetData` endpoint that returns JSON data. You can replace this with your own endpoint as needed. Read more about creating a controller in the [Controllers](../../../implementation/controllers.md) article. {% endhint %} +{% hint style="warning" %} +When using the Fetch API, you need to manually handle errors and authentication. For most scenarios, we recommend using the Umbraco HTTP Client, which provides built-in error handling and authentication. +{% endhint %} + ## Authentication When making requests to the Umbraco API controllers, you may need to include an authorization token in the request headers. This is especially important when making requests to endpoints that require authentication. From e60bde1df2ef37dd0fc9c59024ab6cf47d1cce5c Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 13:26:12 +0200 Subject: [PATCH 20/65] docs: adds links and other helpful tips --- .../customizing/foundation/fetching-data/README.md | 6 ++++-- .../foundation/fetching-data/custom-generated-client.md | 2 ++ .../customizing/foundation/fetching-data/fetch-api.md | 6 +++++- .../customizing/foundation/fetching-data/try-execute.md | 6 +++--- 4 files changed, 14 insertions(+), 6 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 658d6b5448d..47ba5c7d972 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -25,7 +25,7 @@ Here is a quick overview of the two options for you to compare: | Error Handling | Manual | Built-in | | Type Safety | No | Yes | | Request Cancellation | Yes (via AbortController) | Yes (via AbortController) | -| Recommended Use Case | Standard requests | Complex or frequent requests| +| Recommended Use Case | Common requests | Complex or frequent requests | Once you have decided which option to use, you can read more about how to use it below. After that, you can read about how to work with the data you receive from the server. @@ -39,6 +39,8 @@ The Umbraco HTTP Client is a wrapper around the Fetch API that provides a more c ## Handle Requests +Once you have chosen a method to fetch data, the next step is to handle the execution of requests. This includes managing errors, refreshing tokens, and ensuring proper authentication. + ## [Executing Requests](try-execute.md) Executing the request is the next step after fetching data. You can use the `tryExecute` function to handle errors and refresh the token if it is expired. @@ -47,7 +49,7 @@ Executing the request is the next step after fetching data. You can use the `try ### [Custom Generated Client](custom-generated-client.md) -It can be useful to generate a custom client for your API. This can save you a lot of time and effort when working with custom API controllers. +For advanced scenarios, you can generate a custom client for your API using tools like **@hey-api/openapi-ts**. This approach is ideal when working with custom API controllers or when you need type-safe, reusable client code. ## Further Reading diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index b4a50da8ca7..989b05b4f6a 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -30,6 +30,8 @@ npx openapi-ts generate --url https://example.com/openapi.json --output ./my-cli This will generate a TypeScript client in the `./my-client` folder. You can then import the client into your project and use it to make requests to the Management API. +To learn more about OpenAPI and how to define your API specification, visit the [OpenAPI Documentation](https://swagger.io/specification/). + ## Connecting to the Management API You will need to set up a few configuration options in order to connect to the Management API. The following options are required: diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index 25857996c67..74a6e98bd8c 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -80,6 +80,10 @@ console.log(data); The example assumes that you have a valid authentication token. You can replace this with your own token as needed. Read more about authentication in the [Security](../../../implementation/security.md) article. {% endhint %} +{% hint style="warning" %} +When using the Fetch API with `UMB_AUTH_CONTEXT`, you need to handle token expiration errors manually. If the token is expired, the request will return a 401 error. You will need to refresh the token or prompt the user to log in again. +{% endhint %} + Why Use **UMB_AUTH_CONTEXT**? - Simplifies Token Management: Automatically retrieves and refreshes tokens when needed. @@ -87,7 +91,7 @@ Why Use **UMB_AUTH_CONTEXT**? - Reduces Errors: Avoids common pitfalls like expired tokens or incorrect headers. {% hint style="info" %} -The **UMB_AUTH_CONTEXT** is only available in the Backoffice. For external applications, you will need to manage tokens manually or use an API user. Read more about API users in the [API Users article](../../../fundamentals/data/users/api-users.md). +The **UMB_AUTH_CONTEXT** is only available in the Backoffice. For external applications, you will need to manage tokens manually or use an API user. Read more about API users in the [API Users](../../../fundamentals/data/users/api-users.md) article. {% endhint %} ## Management API Controllers diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md index 60878cd2459..aa56ea94832 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md @@ -35,7 +35,7 @@ The `tryExecute` function takes the context of the current class or element as t The above example requires a host element illustrated by the use of `this`. This is typically a custom element that extends the `UmbLitElement` class. {% endhint %} -It is recommended to always use the `tryExecute` function to wrap HTTP requests. +It is recommended to always use the `tryExecute` function to wrap HTTP requests. It simplifies error handling, manages token expiration, and ensures a consistent user experience in the Backoffice. ### Disable Notifications @@ -47,9 +47,9 @@ tryExecute(this, request, { }); ``` -### Cancelling requests +### Cancelling Requests -The `tryExecute` function also supports cancelling requests. This is useful if you want to cancel a request that is taking too long or if the user navigates away from the page. You can cancel a request by using the [AbortController API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController). The `AbortController` API is a built-in API in modern browsers that allows you to cancel requests. You can use it directly with tryExecute: +The `tryExecute` function also supports cancelling requests. This is useful in scenarios where a request is taking too long, or the user navigates away from the page before the request completes. You can cancel a request by using the [AbortController API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController). The `AbortController` API is a built-in API in modern browsers that allows you to cancel requests. You can use it directly with tryExecute: ```javascript const abortController = new AbortController(); From fa5af18577189edf66c7ccab74b6c9b4b232d486 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Wed, 14 May 2025 13:33:19 +0200 Subject: [PATCH 21/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../fetching-data/custom-generated-client.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 989b05b4f6a..6327f499c7a 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -48,13 +48,14 @@ import { client } from './my-client/client.gen'; export const onInit = (host) => { host.consumeContext(UMB_AUTH_CONTEXT, (authContext) => { - // Get the token info from Umbraco - const config = authContext?.getOpenApiConfiguration(); - - client.setConfig({ - auth: config?.token ?? undefined, - baseUrl: config?.base ?? "", - credentials: config?.credentials ?? "same-origin", + // Get the token info from Umbraco + const config = authContext?.getOpenApiConfiguration(); + + client.setConfig({ + auth: config?.token ?? undefined, + baseUrl: config?.base ?? "", + credentials: config?.credentials ?? "same-origin", + }); }); }; ``` From cf56998d776bca7d4da6edec2fde68c6ace93eb9 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Fri, 16 May 2025 09:09:44 +0200 Subject: [PATCH 22/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md Co-authored-by: Lee Kelleher --- .../customizing/foundation/fetching-data/fetch-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index 74a6e98bd8c..f84d4e7de45 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -137,8 +137,8 @@ async function makeRequest(host: UmbClassInterface, url: string, method = 'GET', method, body: body ? JSON.stringify(body) : undefined, headers: { - 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}`, + 'Content-Type': 'application/json', }, }); return response.json(); From c6a5c943d15118a5f16e7ab9679e3dbd7a17d5b2 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Fri, 16 May 2025 09:10:56 +0200 Subject: [PATCH 23/65] Apply suggestions from code review Co-authored-by: Lee Kelleher --- .../customizing/foundation/fetching-data/fetch-api.md | 4 ++-- .../customizing/foundation/fetching-data/http-client.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index f84d4e7de45..20332f0b43f 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -168,8 +168,8 @@ if (response.error) { You can read more about the `tryExecute` function in this article: -{% content-ref url="../try-execute.md" %} -[try-execute.md](../try-execute.md) +{% content-ref url="try-execute.md" %} +[try-execute.md](try-execute.md) {% endcontent-ref %} ## Conclusion diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index d2c2ff7a290..84323632947 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -32,8 +32,8 @@ The recommended approach to use the Umbraco HTTP Client is to use the `tryExecut You can read more about the `tryExecute` function in this article: -{% content-ref url="../try-execute.md" %} -[try-execute.md](../try-execute.md) +{% content-ref url="try-execute.md" %} +[try-execute.md](try-execute.md) {% endcontent-ref %} ## Generate your own client From 95e3067b767aeaa36ddbad1cb0a6c2b78d29f85a Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:18:45 +0200 Subject: [PATCH 24/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/README.md --- .../customizing/foundation/fetching-data/README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 47ba5c7d972..624f9e234aa 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -6,7 +6,13 @@ description: Learn how to request data when extending the Backoffice. ## Fetch Data Through HTTP -There are two main ways to fetch data through HTTP in the Umbraco Backoffice: using the Fetch API or the Umbraco HTTP client. The Fetch API is a modern way to make network requests in JavaScript, while the Umbraco HTTP client is a wrapper around the Fetch API. That provides a more convenient way to make network requests. +There are two main ways to fetch data through HTTP in the Umbraco Backoffice: + +- [Fetch API](#fetch-api) +- [Umbraco HTTP Client](#umbraco-http-client). + +The Fetch API is a modern way to make network requests in JavaScript, while the Umbraco HTTP client is a wrapper around it, providing a more convenient interface. + For most scenarios, we recommend using the Umbraco HTTP Client because it: From ce084da83c264f9ec56b0939ac90dd96f1949ecb Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:18:53 +0200 Subject: [PATCH 25/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/README.md --- 16/umbraco-cms/customizing/foundation/fetching-data/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 624f9e234aa..d08a8f55fe9 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -14,7 +14,7 @@ There are two main ways to fetch data through HTTP in the Umbraco Backoffice: The Fetch API is a modern way to make network requests in JavaScript, while the Umbraco HTTP client is a wrapper around it, providing a more convenient interface. -For most scenarios, we recommend using the Umbraco HTTP Client because it: +For most scenarios, the Umbraco HTTP Client is recommended because it: - Automatically handles authentication and error handling. - Provides type safety for requests and responses. From efca7a40e8885cc000e0a1dcff36dc2bbb46271b Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:19:03 +0200 Subject: [PATCH 26/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/README.md --- 16/umbraco-cms/customizing/foundation/fetching-data/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index d08a8f55fe9..8fc5481526a 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -23,7 +23,7 @@ For most scenarios, the Umbraco HTTP Client is recommended because it: The Fetch API is an alternative for simpler use cases. -Here is a quick overview of the two options for you to compare: +The following table provides a comparison of the two options: | Feature | [Fetch API](fetch-api.md) | [Umbraco HTTP Client](http-client.md) | |------------------------|-------------------------------|------------------------------| From 8478a29913b8f086e980ab960d486554f7cda88b Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:19:10 +0200 Subject: [PATCH 27/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/README.md --- 16/umbraco-cms/customizing/foundation/fetching-data/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 8fc5481526a..122294bbbe0 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -33,7 +33,7 @@ The following table provides a comparison of the two options: | Request Cancellation | Yes (via AbortController) | Yes (via AbortController) | | Recommended Use Case | Common requests | Complex or frequent requests | -Once you have decided which option to use, you can read more about how to use it below. After that, you can read about how to work with the data you receive from the server. +After selecting a method, refer to the sections below for implementation details and guidance on handling the received data. ### [Fetch API](fetch-api.md) From 1610574049c49101534ad374b0144c9e7b54286c Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:19:17 +0200 Subject: [PATCH 28/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/README.md --- 16/umbraco-cms/customizing/foundation/fetching-data/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 122294bbbe0..9bf8d6b8dec 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -41,7 +41,7 @@ The Fetch API is a modern way to make network requests in JavaScript. It provide ### [Umbraco HTTP Client](http-client.md) -The Umbraco HTTP Client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles things like request and response parsing, error handling, and retries. +The Umbraco HTTP Client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles request and response parsing, error handling, and retries. ## Handle Requests From fb99c217a4849cb81e19d7374d769b2e90970adb Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:19:23 +0200 Subject: [PATCH 29/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md --- .../customizing/foundation/fetching-data/http-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index 84323632947..90acf4cb978 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -49,7 +49,7 @@ Read more about generating your own client here: ## Further reading - [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) -- [@umbraco-cms/backoffice/http-client](https://apidocs.umbraco.com/v16/ui-api/modules/packages_core_http-client.html) +- `[@umbraco-cms/backoffice/http-client](https://apidocs.umbraco.com/v16/ui-api/modules/packages_core_http-client.html)` - [Using the Fetch API](fetch-api.md) - [Working with Data](../working-with-data/README.md) - [Creating a Backoffice Entry Point](../../extending-overview/extension-types/backoffice-entry-point.md) From 8e7b26a4b947a239b099f72d25d4ea40a5c16f55 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:19:30 +0200 Subject: [PATCH 30/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 6327f499c7a..d6301511f5e 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -95,5 +95,5 @@ The above example shows how to use the `getMyControllerAction` function, which i ## Further reading -- [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) +- `[@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started)` - [Creating a Backoffice API](../../../tutorials/creating-a-backoffice-api/README.md) From 656054a4acbca76397d7c411303995cdd3c60177 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:19:37 +0200 Subject: [PATCH 31/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md --- .../customizing/foundation/fetching-data/try-execute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md index aa56ea94832..5369c4986d2 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md @@ -4,7 +4,7 @@ description:: Learn how to execute requests in the Backoffice. # Executing Requests -When you make a request to the server, you need to execute it. This can be done using the Fetch API or the Umbraco HTTP client. The Backoffice also provides a `tryExecute` function that you can use to execute requests. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again. +Requests can be made using the Fetch API or the Umbraco HTTP client. The Backoffice also provides a `tryExecute` function that you can use to execute requests. This function handles any errors that occur during the request and automatically refreshes the token if it has expired. If the session has expired, it prompts the user to log in again. {% hint style="info" %} You can read the technical documentation for the `tryExecute` function in the [UI API Documentation](https://apidocs.umbraco.com/v16/ui-api/functions/packages_core_resources.tryExecute.html) class. From ed25570ccff226d388407bb85a44577fc5b3fbf0 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:19:44 +0200 Subject: [PATCH 32/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md --- .../customizing/foundation/fetching-data/try-execute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md index 5369c4986d2..f6c5e9c8230 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md @@ -37,7 +37,7 @@ The above example requires a host element illustrated by the use of `this`. This It is recommended to always use the `tryExecute` function to wrap HTTP requests. It simplifies error handling, manages token expiration, and ensures a consistent user experience in the Backoffice. -### Disable Notifications +### Disabling Notifications The `tryExecute` function will automatically show error bubbles if a request fails. There may be valid cases where you want handle errors yourself. This could for instance be if you want to show a custom error message. You can disable the notifications by passing the `disableNotifications` option to the `tryExecute` function: From 1e03647e79d34f6ca1e20b024eb37a8af39f5ae4 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:19:50 +0200 Subject: [PATCH 33/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md --- .../customizing/foundation/fetching-data/try-execute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md index f6c5e9c8230..ee4f3bd3238 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md @@ -39,7 +39,7 @@ It is recommended to always use the `tryExecute` function to wrap HTTP requests. ### Disabling Notifications -The `tryExecute` function will automatically show error bubbles if a request fails. There may be valid cases where you want handle errors yourself. This could for instance be if you want to show a custom error message. You can disable the notifications by passing the `disableNotifications` option to the `tryExecute` function: +The `tryExecute` function will automatically show error bubbles if a request fails. There may be valid cases where you want to handle errors yourself. This could, for instance, be if you want to show a custom error message. You can disable the notifications by passing the `disableNotifications` option to the `tryExecute` function: ```javascript tryExecute(this, request, { From 0459273edc5c74a061dabc2124c2de7676a8e4c4 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:20:13 +0200 Subject: [PATCH 34/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/README.md --- 16/umbraco-cms/customizing/foundation/fetching-data/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 9bf8d6b8dec..375d8c7c573 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -49,7 +49,7 @@ Once you have chosen a method to fetch data, the next step is to handle the exec ## [Executing Requests](try-execute.md) -Executing the request is the next step after fetching data. You can use the `tryExecute` function to handle errors and refresh the token if it is expired. +After fetching data, the next step is to execute the request. You can use the `tryExecute` function to handle errors and refresh the token if it is expired. ## Advanced Topics From a4d171278a5ec8347e89d4e9d8689690ab7a71bc Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:20:31 +0200 Subject: [PATCH 35/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/README.md --- 16/umbraco-cms/customizing/foundation/fetching-data/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 375d8c7c573..75fdc6afbc8 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -61,4 +61,4 @@ For advanced scenarios, you can generate a custom client for your API using tool ### [Working with Data](../working-with-data/README.md) -Once you have the data using one of the methods above, you can read more about how to work with it here. +After retrieving data using one of the methods above, see the [Working with Data](../working-with-data/README.md) article for more information. From a3b17c32c78bc6c32be8f320312914fe218ca1ff Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:20:44 +0200 Subject: [PATCH 36/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/README.md --- 16/umbraco-cms/customizing/foundation/fetching-data/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 75fdc6afbc8..007f3b0fd08 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -55,7 +55,7 @@ After fetching data, the next step is to execute the request. You can use the `t ### [Custom Generated Client](custom-generated-client.md) -For advanced scenarios, you can generate a custom client for your API using tools like **@hey-api/openapi-ts**. This approach is ideal when working with custom API controllers or when you need type-safe, reusable client code. +For advanced scenarios, you can generate a custom client for your API using tools like `[@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts)`. This approach is ideal when working with custom API controllers or when you need type-safe, reusable client code. ## Further Reading From 150a085e03f752a65961df7738a8bd15d385dc2c Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:20:57 +0200 Subject: [PATCH 37/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index d6301511f5e..69b96e1eaeb 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -4,7 +4,7 @@ description: Learn how to create a custom generated client with TypeScript types # Custom Generated Client -Umbraco uses [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) to generate its HTTP client for the OpenAPI specification of the Management API. It is available through the `@umbraco-cms/backoffice/http-client` package. +Umbraco uses `[@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started)` to generate its HTTP client for the OpenAPI specification of the Management API. It is available through the `@umbraco-cms/backoffice/http-client` package. {% content-ref url="http-client.md" %} [http-client.md](http-client.md) From 538ed007209525f318e43b16235f85e2ef6a8da6 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:21:09 +0200 Subject: [PATCH 38/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 69b96e1eaeb..2c9f3dfc586 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -10,7 +10,7 @@ Umbraco uses `[@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started)` [http-client.md](http-client.md) {% endcontent-ref %} -The following examples will show you how to generate a client from an OpenAPI specification and how to use it in your project. We use the **@hey-api/openapi-ts** library, but the same principles apply to any other library that generates a TypeScript client. +The following examples show how to generate a client from an OpenAPI specification and how to use it in the project. Below, the `@hey-api/openapi-ts` library is used, but the same principles apply to any other library that generates a TypeScript client. ## Generate your own client From a29574f9e682963cb45d7378800dd93f5090f464 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:21:22 +0200 Subject: [PATCH 39/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 2c9f3dfc586..e33944732f2 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -14,7 +14,7 @@ The following examples show how to generate a client from an OpenAPI specificati ## Generate your own client -The generated client provides a convenient way to make requests to that specific API with type-safety without having to manually write the requests yourself. You can consider generating a client. This can save you a lot of time and effort when working with custom API controllers. +The generated client provides a convenient way to make requests to the specified API with type-safety without having to manually write the requests yourself. Consider generating a client to save time and reduce effort when working with custom API controllers. To get started, you can install the generator using the following command: From 3fceda7269cc1c39c4de2e193e99e284f84469ec Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:21:34 +0200 Subject: [PATCH 40/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index e33944732f2..906fd06de2a 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -16,7 +16,7 @@ The following examples show how to generate a client from an OpenAPI specificati The generated client provides a convenient way to make requests to the specified API with type-safety without having to manually write the requests yourself. Consider generating a client to save time and reduce effort when working with custom API controllers. -To get started, you can install the generator using the following command: +To get started, install the generator using the following command: ```bash npm install @hey-api/openapi-ts From 89e917f967ae3c57f5d2e4f95925a9f3b90ca018 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:21:45 +0200 Subject: [PATCH 41/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 906fd06de2a..b65b676aff7 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -22,7 +22,7 @@ To get started, install the generator using the following command: npm install @hey-api/openapi-ts ``` -Then, you can use the `openapi-ts` command to generate a client from your OpenAPI specification: +Then, use the `openapi-ts` command to generate a client from your OpenAPI specification: ```bash npx openapi-ts generate --url https://example.com/openapi.json --output ./my-client From 742d345eb324363f88510a5f206e07293a81014d Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:21:57 +0200 Subject: [PATCH 42/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index b65b676aff7..c5d533101e2 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -28,7 +28,7 @@ Then, use the `openapi-ts` command to generate a client from your OpenAPI specif npx openapi-ts generate --url https://example.com/openapi.json --output ./my-client ``` -This will generate a TypeScript client in the `./my-client` folder. You can then import the client into your project and use it to make requests to the Management API. +This will generate a TypeScript client in the `./my-client` folder. Import the generated client into your project to make requests to the Management API. To learn more about OpenAPI and how to define your API specification, visit the [OpenAPI Documentation](https://swagger.io/specification/). From ed1df4fc7acc3a3f147710d7963a11ed75930aec Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:22:12 +0200 Subject: [PATCH 43/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index c5d533101e2..9c26bee70ad 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -60,7 +60,7 @@ export const onInit = (host) => { }; ``` -This will set up the HTTP client to use the Management API base URL and authentication method. You can then use the client to make requests to the Management API. +This sets up the HTTP client with the Management API’s base URL and authentication method.. You can then use the client to make requests to the Management API. {% hint style="info" %} You can see the above example in action by looking at the [Umbraco Extension Template](../../development-flow/umbraco-extension-template.md). From 16dfc1882290b627647b213684f059bd180d60e5 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:22:24 +0200 Subject: [PATCH 44/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 9c26bee70ad..953c6b7bd82 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -63,7 +63,7 @@ export const onInit = (host) => { This sets up the HTTP client with the Management API’s base URL and authentication method.. You can then use the client to make requests to the Management API. {% hint style="info" %} -You can see the above example in action by looking at the [Umbraco Extension Template](../../development-flow/umbraco-extension-template.md). +See the example in action in the [Umbraco Extension Template](../../development-flow/umbraco-extension-template.md). {% endhint %} **Fetch API** From f95779948ac26dbe83147279d082313dfab9b018 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:22:51 +0200 Subject: [PATCH 45/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 953c6b7bd82..e27bf3bee1a 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -68,7 +68,7 @@ See the example in action in the [Umbraco Extension Template](../../development- **Fetch API** -The approach with a Backoffice Entry Point is good if you have a lot of requests to make. However, if you only have a few requests to make, you can use the `fetch` function directly. Read more about that here: +A Backoffice Entry Point is recommended when working with multiple requests. However, if you only have a few requests to make, you can use the `fetch` function directly. Read more about that here: {% content-ref url="fetch-api.md" %} [fetch-api.md](fetch-api.md) From fcba0655babeca4821e62066dd38886a61c84dd0 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:23:03 +0200 Subject: [PATCH 46/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index e27bf3bee1a..6f117d34938 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -66,7 +66,7 @@ This sets up the HTTP client with the Management API’s base URL and authentica See the example in action in the [Umbraco Extension Template](../../development-flow/umbraco-extension-template.md). {% endhint %} -**Fetch API** +### Fetch API A Backoffice Entry Point is recommended when working with multiple requests. However, if you only have a few requests to make, you can use the `fetch` function directly. Read more about that here: From 5822dddf74a369cc2e1ed7a49afbe08ef5833c10 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:23:17 +0200 Subject: [PATCH 47/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 6f117d34938..79fa75f57a3 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -91,7 +91,7 @@ if (data) { } ``` -The above example shows how to use the `getMyControllerAction` function, which is generated through `openapi-ts`. The `client` parameter is the HTTP client that you want to use. You can use any HTTP client that implements the underlying interface from **@hey-api/openapi-ts**, which the Umbraco HTTP Client does. The `getMyControllerAction` function will then use the Umbraco HTTP client over its own to make the request to the Management API. +The above example shows how to use the `getMyControllerAction` function, which is generated through `openapi-ts`. The `client` parameter is the HTTP client that you want to use. You can use any HTTP client that implements the underlying interface from `@hey-api/openapi-ts`, which the Umbraco HTTP Client does. The `getMyControllerAction` function will then use the Umbraco HTTP client over its own to make the request to the Management API. ## Further reading From ebae84fcbe9f12b458c584a06a832f7640eb0505 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:23:29 +0200 Subject: [PATCH 48/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md --- .../customizing/foundation/fetching-data/fetch-api.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index 20332f0b43f..0617cd77ce2 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -32,9 +32,6 @@ if (data) { } ``` -{% hint style="info" %} -The example assumes that you have a controller set up at the `/umbraco/MyApiController/GetData` endpoint that returns JSON data. You can replace this with your own endpoint as needed. Read more about creating a controller in the [Controllers](../../../implementation/controllers.md) article. -{% endhint %} {% hint style="warning" %} When using the Fetch API, you need to manually handle errors and authentication. For most scenarios, we recommend using the Umbraco HTTP Client, which provides built-in error handling and authentication. From 7e796c869edc59250de2a3ea70c8629193053c03 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:23:41 +0200 Subject: [PATCH 49/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md --- .../customizing/foundation/fetching-data/fetch-api.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index 0617cd77ce2..6b0b16b4d0b 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -13,7 +13,13 @@ The Fetch API is a great way to make network requests in Umbraco because it prov ### Example -For this example, we are using the Fetch API to make a GET request to the `/umbraco/MyApiController/GetData` endpoint. The response is then parsed as JSON and logged to the console. If there is an error with the request, it is caught and logged to the console: +For this example, we are using the Fetch API to make a GET request to the `/umbraco/MyApiController/GetData` endpoint. The response is then parsed as JSON and logged to the console. + +{% hint style="info" %} +The example assumes that you have a controller set up at the `/umbraco/MyApiController/GetData` endpoint that returns JSON data. You can replace this with your own endpoint as needed. Read more about creating a controller in the [Controllers](../../../implementation/controllers.md) article. +{% endhint %} + +If there is an error with the request, it is caught and logged to the console: ```javascript const data = await fetch('/umbraco/MyApiController/GetData') From e7fa87b6ea48ca556b926eced997edf0437ac8b8 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:23:59 +0200 Subject: [PATCH 50/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md --- .../customizing/foundation/fetching-data/fetch-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index 6b0b16b4d0b..8f3b416a7f5 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -177,6 +177,6 @@ You can read more about the `tryExecute` function in this article: ## Conclusion -The Fetch API is a powerful and flexible way to make network requests in JavaScript. It is available in all modern browsers and is the recommended way to make network requests in JavaScript. The Fetch API can be used in Umbraco to make network requests to the server. It can also be used to make requests to the Management API controllers. You can use the Fetch API to make requests to any endpoint in the Management API. You can also use it to handle responses in a variety of formats. This is especially useful, if you have but a few requests to make. +The Fetch API is a powerful and flexible way to make network requests in JavaScript. It is available in all modern browsers and is the recommended way to make network requests in JavaScript. The Fetch API can be used in Umbraco to make network requests to the server. It can also be used to make requests to the Management API controllers. You can use the Fetch API to make requests to any endpoint in the Management API. You can also use it to handle responses in a variety of formats. This is useful if you only need to make a few requests. However, if you have a lot of requests to make, you might want to consider an alternative approach. You could use a library like [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) to generate a TypeScript client. The library requires an OpenAPI definition and allows you to make requests to the Management API without having to manually write the requests yourself. The generated client will only need the token once. This can save you a lot of time and effort when working with the Management API. The Umbraco Backoffice itself is running with this library and even exports its internal HTTP client. You can read more about this in the [HTTP Client](http-client.md) article. From 97b8ac914686a0045dacb56f31a3f9053bfeba6d Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:24:13 +0200 Subject: [PATCH 51/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md --- .../customizing/foundation/fetching-data/fetch-api.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index 8f3b416a7f5..5d887abff93 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -79,9 +79,6 @@ const data = await fetchData(this, '/umbraco/management/api/v1/server/status'); console.log(data); ``` -{% hint style="info" %} -The example assumes that you have a valid authentication token. You can replace this with your own token as needed. Read more about authentication in the [Security](../../../implementation/security.md) article. -{% endhint %} {% hint style="warning" %} When using the Fetch API with `UMB_AUTH_CONTEXT`, you need to handle token expiration errors manually. If the token is expired, the request will return a 401 error. You will need to refresh the token or prompt the user to log in again. From c91b4f96ee7bf02cf9adf2c05e9d18b79a0163fc Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:24:24 +0200 Subject: [PATCH 52/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md --- .../customizing/foundation/fetching-data/fetch-api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index 5d887abff93..e17ef8dc60d 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -51,6 +51,10 @@ The Fetch API does not automatically include authentication tokens in requests. ### Example: Using `UMB_AUTH_CONTEXT` for Authentication +{% hint style="info" %} +The example assumes that you have a valid authentication token. You can replace this with your own token as needed. Read more about authentication in the [Security](../../../implementation/security.md) article. +{% endhint %} + The following example demonstrates how to use `UMB_AUTH_CONTEXT` to retrieve the latest token and make an authenticated request: ```javascript From ac48356f92d997981bcbfdf1ed232662ae089e73 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:24:37 +0200 Subject: [PATCH 53/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md --- .../customizing/foundation/fetching-data/fetch-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md index e17ef8dc60d..b21582a6b94 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md @@ -149,7 +149,7 @@ async function makeRequest(host: UmbClassInterface, url: string, method = 'GET', } ``` -The above example serves to illustrate some of the process to make a request to the Management API. You can use this function to make requests to any endpoint in the Management API. The function does not handle errors or responses, so you will need to add that logic yourself, nor does it handle the authentication process. If the token is timed out, you will get a 401 error back, if the `getLatestToken` method failed to refresh the token. +The above example illustrates the process of making a request to the Management API. You can use this function to make requests to any endpoint in the Management API. The function does not handle errors or responses, so you will need to add that logic yourself, nor does it handle the authentication process. If the token is timed out, you will get a 401 error back, if the `getLatestToken` method failed to refresh the token. ## Executing the request From 7b4d4bfdce7ce393ddff6313e72908ebd3f14bc6 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:24:57 +0200 Subject: [PATCH 54/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md --- .../customizing/foundation/fetching-data/http-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index 90acf4cb978..e65df36fce2 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -4,7 +4,7 @@ description: Learn more about working with the Umbraco HTTP Client. # HTTP Client -The Umbraco Backoffice provides a built-in HTTP client that you can use to make network requests. This client is colloquially known as the Umbraco HTTP Client. It is generated using **@hey-api/openapi-ts** around the OpenAPI specification and is available through the `@umbraco-cms/backoffice/http-client` package. +The Umbraco Backoffice includes a built-in HTTP client commonly referred to as the Umbraco HTTP Client for making network requests. It is generated using `@hey-api/openapi-ts` around the OpenAPI specification and is available through the `@umbraco-cms/backoffice/http-client` package. **Example:** From 69b4b52ef216188af14e21330389f9a05a40e9ea Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:25:14 +0200 Subject: [PATCH 55/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md --- .../customizing/foundation/fetching-data/http-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index e65df36fce2..f27a61f4091 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -20,7 +20,7 @@ if (data) { } ``` -The above example shows how to use the Umbraco HTTP client to make a GET request to the Management API. The `umbHttpClient` object provides methods for making requests, including `get`, `post`, `put`, and `delete`. Each method takes an options object that specifies the URL, headers, and body of the request. +The above example shows how to use the Umbraco HTTP client to make a GET request to the Management API. The `umbHttpClient` object provides methods for making requests, including `get`, `post`, `put`, and `delete`. Each method accepts an options object with the URL, headers, and body of the request. The Umbraco HTTP client automatically handles authentication and error handling, so you don't have to worry about those details. It also provides a convenient way to parse the response data as JSON. From 813114052ed50020ec7b69e4d8c757c26c65bc5d Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:25:32 +0200 Subject: [PATCH 56/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md --- .../customizing/foundation/fetching-data/http-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index f27a61f4091..58809bb4067 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -26,7 +26,7 @@ The Umbraco HTTP client automatically handles authentication and error handling, ## Using the Umbraco HTTP Client -The Umbraco HTTP client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles things like request and response parsing, error handling, and retries. The Umbraco HTTP client is available through the `@umbraco-cms/backoffice/http-client` package, which is included in the Umbraco Backoffice. You can use it to make requests to any endpoint in the Management API or to any other API. +The Umbraco HTTP client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles request and response parsing, error handling, and retries. The Umbraco HTTP client is available through the `@umbraco-cms/backoffice/http-client` package, which is included in the Umbraco Backoffice. You can use it to make requests to any endpoint in the Management API or to any other API. The recommended approach to use the Umbraco HTTP Client is to use the `tryExecute` function. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again. From 9eece0d4b65772133324e6f11161f1767bbd0c00 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:25:49 +0200 Subject: [PATCH 57/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md --- .../customizing/foundation/fetching-data/http-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index 58809bb4067..2047d4b5e3e 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -28,7 +28,7 @@ The Umbraco HTTP client automatically handles authentication and error handling, The Umbraco HTTP client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles request and response parsing, error handling, and retries. The Umbraco HTTP client is available through the `@umbraco-cms/backoffice/http-client` package, which is included in the Umbraco Backoffice. You can use it to make requests to any endpoint in the Management API or to any other API. -The recommended approach to use the Umbraco HTTP Client is to use the `tryExecute` function. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again. +The recommended way to use the Umbraco HTTP Client is with the `tryExecute` function. This function handles any errors that occur during the request and automatically refreshes the token if it has expired. If the session has expired, it prompts the user to log in again. You can read more about the `tryExecute` function in this article: From 9eefa33e62e81ec12b04ded44dd222e6c3da2552 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:26:06 +0200 Subject: [PATCH 58/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md --- .../customizing/foundation/fetching-data/http-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index 2047d4b5e3e..ea6197d6281 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -36,7 +36,7 @@ You can read more about the `tryExecute` function in this article: [try-execute.md](try-execute.md) {% endcontent-ref %} -## Generate your own client +## Generating a Custom Client You can also generate your own client using the **@hey-api/openapi-ts** library. This library allows you to generate a TypeScript client from an OpenAPI specification. The generated client will handle authentication and error handling for you, so you don't have to worry about those details. From 930d333703e021b666148b458d0df5405885f1b2 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:26:24 +0200 Subject: [PATCH 59/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md --- .../customizing/foundation/fetching-data/http-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index ea6197d6281..3dfa4bc180e 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -48,7 +48,7 @@ Read more about generating your own client here: ## Further reading -- [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) +- `[@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started)` - `[@umbraco-cms/backoffice/http-client](https://apidocs.umbraco.com/v16/ui-api/modules/packages_core_http-client.html)` - [Using the Fetch API](fetch-api.md) - [Working with Data](../working-with-data/README.md) From b90ba6ad884086e6e70502b086d8a7cf17894690 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:30:02 +0200 Subject: [PATCH 60/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md --- .../customizing/foundation/fetching-data/http-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index 3dfa4bc180e..da5f3f36bab 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -38,7 +38,7 @@ You can read more about the `tryExecute` function in this article: ## Generating a Custom Client -You can also generate your own client using the **@hey-api/openapi-ts** library. This library allows you to generate a TypeScript client from an OpenAPI specification. The generated client will handle authentication and error handling for you, so you don't have to worry about those details. +You can also generate your own client using the `@hey-api/openapi-ts` library. This library allows you to generate a TypeScript client from an OpenAPI specification. The generated client will handle authentication and error handling for you, so you don't have to worry about those details. Read more about generating your own client here: From 545c7cdfd3bd2b7f8e3e29cee4274981819677ea Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:30:25 +0200 Subject: [PATCH 61/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md --- .../customizing/foundation/fetching-data/http-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index da5f3f36bab..6cd9d24698b 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -48,7 +48,7 @@ Read more about generating your own client here: ## Further reading -- `[@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started)` +- [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) - `[@umbraco-cms/backoffice/http-client](https://apidocs.umbraco.com/v16/ui-api/modules/packages_core_http-client.html)` - [Using the Fetch API](fetch-api.md) - [Working with Data](../working-with-data/README.md) From d4b5a1a9268cfc2d8caff56d953c29303aace3d0 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:30:44 +0200 Subject: [PATCH 62/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md --- .../customizing/foundation/fetching-data/http-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md index 6cd9d24698b..a1d353338d5 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/http-client.md @@ -49,7 +49,7 @@ Read more about generating your own client here: ## Further reading - [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) -- `[@umbraco-cms/backoffice/http-client](https://apidocs.umbraco.com/v16/ui-api/modules/packages_core_http-client.html)` +- [@umbraco-cms/backoffice/http-client](https://apidocs.umbraco.com/v16/ui-api/modules/packages_core_http-client.html) - [Using the Fetch API](fetch-api.md) - [Working with Data](../working-with-data/README.md) - [Creating a Backoffice Entry Point](../../extending-overview/extension-types/backoffice-entry-point.md) From 3dc3c9ef09c6572073f409f1a35e0a3e62c587cd Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:31:39 +0200 Subject: [PATCH 63/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 79fa75f57a3..90ae7c6cd48 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -4,7 +4,7 @@ description: Learn how to create a custom generated client with TypeScript types # Custom Generated Client -Umbraco uses `[@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started)` to generate its HTTP client for the OpenAPI specification of the Management API. It is available through the `@umbraco-cms/backoffice/http-client` package. +Umbraco uses [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) to generate its HTTP client for the OpenAPI specification of the Management API. It is available through the `@umbraco-cms/backoffice/http-client` package. {% content-ref url="http-client.md" %} [http-client.md](http-client.md) From d88e2d25bb4ac6a54933754817b716e6af69ec22 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:32:10 +0200 Subject: [PATCH 64/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/README.md --- 16/umbraco-cms/customizing/foundation/fetching-data/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/README.md b/16/umbraco-cms/customizing/foundation/fetching-data/README.md index 007f3b0fd08..46469d6762e 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/README.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/README.md @@ -55,7 +55,7 @@ After fetching data, the next step is to execute the request. You can use the `t ### [Custom Generated Client](custom-generated-client.md) -For advanced scenarios, you can generate a custom client for your API using tools like `[@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts)`. This approach is ideal when working with custom API controllers or when you need type-safe, reusable client code. +For advanced scenarios, you can generate a custom client for your API using tools like [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts). This approach is ideal when working with custom API controllers or when you need type-safe, reusable client code. ## Further Reading From 682e1371e29906cd7f8f4e8d1ed3a6b84d59036b Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Fri, 16 May 2025 10:32:48 +0200 Subject: [PATCH 65/65] Update 16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md --- .../foundation/fetching-data/custom-generated-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md index 90ae7c6cd48..0729a3e1921 100644 --- a/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md +++ b/16/umbraco-cms/customizing/foundation/fetching-data/custom-generated-client.md @@ -95,5 +95,5 @@ The above example shows how to use the `getMyControllerAction` function, which i ## Further reading -- `[@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started)` +- [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) - [Creating a Backoffice API](../../../tutorials/creating-a-backoffice-api/README.md)