You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: 16/umbraco-cms/customizing/foundation/fetching-data/README.md
+7-1Lines changed: 7 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,6 +34,12 @@ The HTTP Client is a wrapper around the Fetch API that provides a more convenien
34
34
35
35
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.
36
36
37
-
## [Working with Data](../working-with-data/README.md)
description: Learn how to create a custom generated client with TypeScript types for your OpenAPI specification.
3
+
---
4
+
5
+
# Custom Generated Client
6
+
7
+
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.
8
+
9
+
{% content-ref url="http-client.md" %}
10
+
[http-client.md](http-client.md)
11
+
{% endcontent-ref %}
12
+
13
+
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.
14
+
15
+
If you want to generate your own client, you can use the following command:
16
+
17
+
```bash
18
+
npm install @hey-api/openapi-ts
19
+
```
20
+
21
+
Then, you can use the `openapi-ts` command to generate a client from your OpenAPI specification:
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.
28
+
29
+
### Connecting to the Management API
30
+
31
+
You will need to set up a few configuration options in order to connect to the Management API. The following options are required:
32
+
33
+
-`auth`: The authentication method to use. This is typically `Bearer` for the Management API.
34
+
-`baseUrl`: The base URL of the Management API. This is typically `https://example.com/umbraco/api/management/v1`.
35
+
-`credentials`: The credentials to use for the request. This is typically `same-origin` for the Management API.
36
+
37
+
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:
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.
57
+
58
+
{% hint style="info" %}
59
+
You can see the above example in action by looking at the [Umbraco Extension Template](../../development-flow/umbraco-extension-template.md).
60
+
{% endhint %}
61
+
62
+
**Fetch API**
63
+
64
+
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:
65
+
66
+
{% content-ref url="fetch-api.md" %}
67
+
[fetch-api.md](fetch-api.md)
68
+
{% endcontent-ref %}
69
+
70
+
**Setting the client directly**
71
+
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.
const { data } =awaittryExecute(this, getMyControllerAction({
79
+
client: umbHttpClient, // Use Umbraco's HTTP client
80
+
}));
81
+
82
+
if (data) {
83
+
console.log('Server status:', data);
84
+
}
85
+
```
86
+
87
+
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.
Copy file name to clipboardExpand all lines: 16/umbraco-cms/customizing/foundation/fetching-data/http-client.md
+5-76Lines changed: 5 additions & 76 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,91 +34,20 @@ You can read more about the `tryExecute` function in this article:
34
34
[try-execute.md](../try-execute.md)
35
35
{% endcontent-ref %}
36
36
37
-
```javascript
38
-
39
-
## Custom Generated Client
40
-
41
-
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.
42
-
43
-
If you want to generate your own client, you can use the following command:
37
+
## Generate your own client
44
38
45
-
```bash
46
-
npm install @hey-api/openapi-ts
47
-
```
48
-
49
-
Then, you can use the `openapi-ts` command to generate a client from your OpenAPI specification:
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.
54
40
55
-
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.
56
-
57
-
### Connecting to the Management API
58
-
59
-
You will need to set up a few configuration options in order to connect to the Management API. The following options are required:
60
-
61
-
-`auth`: The authentication method to use. This is typically `Bearer`for the Management API.
62
-
-`baseUrl`: The base URLof the Management API. This is typically `https://example.com/umbraco/api/management/v1`.
63
-
-`credentials`: The credentials to use for the request. This is typically `same-origin`for the Management API.
64
-
65
-
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:
66
-
67
-
```javascript
68
-
import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth';
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.
85
-
86
-
{% hint style="info"%}
87
-
You can see the above example in action by looking at the [Umbraco Extension Template](../../development-flow/umbraco-extension-template.md).
88
-
{% endhint %}
89
-
90
-
**Fetch API**
91
-
92
-
The approach with a Backoffice EntryPoint 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:
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.
100
-
101
-
```javascript
102
-
import { getMyControllerAction } from './my-client';
103
-
import { tryExecute } from '@umbraco-cms/backoffice/resources';
104
-
import { umbHttpClient } from '@umbraco-cms/backoffice/http-client';
105
-
106
-
const { data } = await tryExecute(this, getMyControllerAction({
107
-
client: umbHttpClient, // Use Umbraco's HTTP client
108
-
}));
109
-
110
-
if (data) {
111
-
console.log('Server status:', data);
112
-
}
113
-
```
114
-
115
-
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.
0 commit comments