Custom Generated Client

Umbraco uses @hey-api/openapi-ts to generate its HTTP client for the OpenAPI specification of the Management API. It is available through the @umbraco-cms/backoffice/http-client package.

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

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, install the generator using the following command:

Then, use the openapi-ts command to generate a client from your OpenAPI specification:

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 .

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

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 that sets up the configuration options for the HTTP client:

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.

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:

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.

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