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.

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`);
            

fetchApp

This method lets the app communicate with the custom HTTP handler and invoke its methods.

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

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});
            

Last modified: 19 September 2024