Custom Generated Client

Learn how to create a custom generated client with TypeScript types for your OpenAPI specification.

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.

Umbraco HTTP 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

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:

npm install @hey-api/openapi-ts

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

npx openapi-ts generate --url https://example.com/openapi.json --output ./my-client

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.

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

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 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.

See the example in action in the Umbraco Extension Template.

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:

Fetch API

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.

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 Umbraco HTTP client over its own to make the request to the Management API.

Further reading

• @hey-api/openapi-ts
• Creating a Backoffice API