Host API

Host API is the supplementary API that supports communication between different parts of an app and YouTrack.

How to Use the Host API

When you want your widget to send HTTP requests to YouTrack or communicate with it using any of the YouTrack APIs, you must include a script that registers the widget in YouTrack in the HTML code of the widget.

Here you can see an example of the registration script:

            <script type="module">
                const host = await YTApp.register();
                host.alert('Hello world');
            </script>
        

When you've registered the widget, you can use the Host API to send alerts in YouTrack or invoke functions implemented as custom HTTP handlers.

Host API Reference

Here is the list of methods that the Host API supports.

alert

This method allows you to send an alert message to YouTrack from within an app.

Parameter	Type	Description	Required
`message`	String	The text of the alert message.	✓

Here you can find a sample code that uses this method:

                const host = await YTApp.register();
                host.alert('Hello world');
            

fetchYouTrack

This method lets the app use the YouTrack REST API.

Parameter	Type	Description	Required
`relativeURL`	String	The relative URL to the REST API endpoint.	✓
`requestParams`	RequestParams	Optional fetch parameters. For additional information, see requestParams below.

Parameter

Type

Description

Required

relativeURL

String

The relative URL to the REST API endpoint.

✓

requestParams

RequestParams

Optional fetch parameters.

For additional information, see requestParams below.

Here you can find a sample code that uses this method:

                const host = await YTApp.register();
                const user = await host.fetchYouTrack(`users/${YTApp.entity.id}?fields=id,login,name`);
            

Here's a sample that contains optional query parameters:

                const ytResponse = await host.fetchYouTrack('users', {query: {fields: 'id,login,email'});
            

fetchApp

This method lets the app communicate with the custom HTTP handler and invoke its methods. The fetchApp method is similar to the fetchYouTrack method, but has an additional scope parameter. This parameter lets you indicate whether the request should be made to a scoped or global endpoint.

The fetchApp method parses JSON and returns a ready-to-use response object.

Parameter	Type	Description	Required
`relativeURL`	String	The relative URL to the custom HTTP endpoint. For more details, see HTTP Handlers.	✓
`requestParams`	RequestParams & {scope: boolean}	Optional fetch parameters. For details, see requestParams below. You have the option to set the scope for the handler in this parameter. Pass an empty object to set the scope to `global`. When the HTTP handler you're trying to access has limited scope, set the scope to `true`. This ensures that the scope entity will be available for the handler from the context. For more details, see Scope.

Parameter

Type

Description

Required

relativeURL

String

The relative URL to the custom HTTP endpoint. For more details, see HTTP Handlers.

✓

requestParams

RequestParams & {scope: boolean}

Optional fetch parameters. For details, see requestParams below.

You have the option to set the scope for the handler in this parameter. Pass an empty object to set the scope to global.

When the HTTP handler you're trying to access has limited scope, set the scope to true. This ensures that the scope entity will be available for the handler from the context. For more details, see Scope.

Here you can find a sample code that uses this method:

                const host = await YTApp.register();
                const appResponse = await host.fetchApp('backend/demo', {scope: true});
            

Here's a sample GET request with query parameters:

                const appResponse = await host.fetchApp('backend/demo', {query: {key: '12345', count: 20, filter: true});
            

Here's a sample POST request with body:

                const appResponse = await host.fetchApp('backend/demo', {method: 'POST', body: {test: 'test'}});
            

requestParams

The requestParams object is basically an extension of the requestInit object used to customize requests in the Fetch API. In addition to the base properties supported by the requestInit object, requestParams supports the following supplemental properties:

Property	Description
`query`	A JavaScript object that contains key-value pairs that are used as query parameters for the HTTP request. For example: const query = { key: '12345', shelterID: 'abc00', count: 20, animals: true };
`scope`	A Boolean property that indicates if the request should be made to a scoped or global endpoint. For example: // appResponse is a parsed JSON: const appResponse = await host.fetchApp('backend/demo', {scope: true}); console.log('test', appResponse.test);

Apps that use the DASHBOARD_WIDGET and MARKDOWN extension points generate a special embedding component each time its widgets are inserted into a dashboard or text field. This component stores the data the widget displays in these locations. As a result, these widgets are supported by a more extensive API that we call the CustomWidgetAPILayer.

Here is the list of additional methods that are supported for these extension points.

setTitle

setTitle(label: string, ?labelUrl: string): void

Sets the text displayed in the widget header. If a value is specified for the labelUrl parameter, the text is set as a link to the target URL.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

Parameter	Type	Description	Required
`label`	String	The string that is shown as the widget title.	✓
`labelURL`	String	The address of the target page that opens when a user clicks the widget title. If this optional parameter is not specified, the widget title is set as text only.

setLoadingAnimationEnabled

setLoadingAnimationEnabled(isEnabled: boolean): void

Toggles the image rotation animation for the widget reload icon. Call this method when the widget populates data from a remote server to indicate that a process is running in the background.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

Parameter	Type	Description	Required
`isEnabled`	Boolean	Determines whether the widget reload icon rotates or not.	✓

enterConfigMode

enterConfigMode(): void

Invokes configuration mode. When in configuration mode, the visual presentation of the widget changes to indicate that its settings can be updated. The refresh icon is also hidden.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

exitConfigMode

exitConfigMode(): void

Exits configuration mode.

setError

setError(e: Error): void

Sets an error state in the widget, displaying an error message or taking other error-handling actions.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

Parameter	Type	Description	Required
`e`	Error	The error object containing details about the error.	✓

clearError

clearError(): void

Clears any previously set error state in the widget.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

readCache

readCache(): Promise<unknown>

Reads data previously stored in the cache. Returns a promise that resolves to the cached data.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

storeCache

storeCache(data: unknown): Promise<Void>

Stores any object in the client-side cache. Use this method to store populated data locally and display it immediately in the widget, then refresh it from the server. Returns a promise that resolves when the data is successfully stored.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

Parameter	Type	Description	Required
`data`	Unknown	Specifies the data to be stored in the cache.	✓

readConfig

readConfig(): Promise<unknown>

Reads the widget configuration data. Returns a promise that resolves to the configuration data.

The schema for the config object must be declared in the settingsSchemaPath property of the widget manifest. Any undeclared payloads are ignored.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

storeConfig

storeConfig(config: unknown): Promise<Void>

Stores configuration data for the widget. Exits configuration mode if configuration mode is active.

The schema for the config object must be declared in the settingsSchemaPath property of the widget manifest. Any undeclared payloads are ignored.

Returns a promise that resolves when the configuration data is successfully stored.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

Parameter	Type	Description	Required
`config`	Unknown	The configuration data to be stored.	✓

downloadFile

downloadFile(serviceID: string, relativeURL: string, requestParams: unknown, fileName?: string): Promise<void>

Downloads a file from a specified service.

Returns a promise that resolves when the file is successfully downloaded.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

Parameter	Type	Description	Required
`serviceID`	String	The ID of the service from which the file will be downloaded.	✓
relativeURL	String	The relative URL path to the file within the service.	✓
requestParams	Unknown	Parameters to be included in the request.	✓
fileName	String	The name of the file to be downloaded. If not specified, the service may provide a default name.

fetchHub

fetchHub(relativeURL: string, requestParams: RequestParams): unknown

Fetches data from the Hub service that is connected to or built into YouTrack. Similar to the fetch method but specifically designed for Hub services.

Returns the fetched data. The return type depends on the information retrieved from the service.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

Parameter	Type	Description	Required
`relativeURL`	String	Sets the URL to the Hub service API endpoint. This is the path to the resource that you want to fetch. The URL is relative to the server home URL. For more information, refer to the Hub documentation.	✓
`requestParams`	RequestParams	Optional parameters that you want to include in the request.

For example:

CustomWidgetAPILayer.fetchHub('api/rest/users/me?fields=name,login,profile(avatar(url))')
                .then(response => console.log(response));

The following example shows how to use this method in a POST request:

host.fetchHub('api/rest/users/me', {
                method: 'POST',
                body: {favoriteProjects: []}
                })
                .then(response => console.log(response));

alert

alert(...args: Parameters<(typeof AlertService)['addAlert']>): void

Displays a system alert in the lower left corner of the page.

This is a wrapper for the AlertService component from the JetBrains Ring UI component library.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

Parameter	Type	Description	Required
`args`	Parameters	The parameters required by the `addAlert` method of the `AlertService`.	✓

For example:

host.alert('Hello world', 'success', 5000)

removeWidget(): void

Removes the embedded widget from the user interface.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

Last modified: 7 November 2024

Developer Portal for YouTrack and Hub Help

Host API

How to Use the Host API

Host API Reference

alert

fetchYouTrack

fetchApp

requestParams

Custom Widget API Reference

setTitle

setLoadingAnimationEnabled

enterConfigMode

exitConfigMode

setError

clearError

readCache

storeCache

readConfig

storeConfig

downloadFile

fetchHub

alert

removeWidget