HTTP Handlers

HTTP handlers let you make YouTrack data accessible from custom HTTP endpoints. These handlers extend the REST API so clients can call these endpoints like any other YouTrack REST API endpoint, not just the frontend code for a specific widget. This means you can use HTTP handlers to provision webhooks that can be accessed by third-party services.

YouTrack supports custom HTTP handlers written in JavaScript. The current YouTrack JavaScript implementation is compatible with the latest ECMAScript specification.

Sample HTTP Handler

Here is a sample script for implementing a custom HTTP handler:

          exports.httpHandler = {
              endpoints: [
                  {
                      scope: "issue",
                      method: "GET",
                      path: "demo",
                      permissions: ['READ_ISSUE', 'READ_USERGROUP'],
                      handle: function (ctx) {
                          ctx.response.json({message: "Hello World"});
                      }
                  }
              ]
          }
        

HTTP Handler API

Here is the reference for the script that implements a custom HTTP handler.

Each script exports one HTTP handler to the exports.httpHandler property. The HTTP handler is declared as an object containing the array of endpoints.

Endpoints

Each endpoint contains the following properties:

Property	Description
`scope`	The scope entity of the endpoint. Setting the scope guarantees you that the scope entity will be available in the context of the `handle` function. YouTrack supports the following scopes: `issue`, `project`, `article`, `user`, `global`. Default value: `global`. For more details, see Scope.
`method`	The HTTP method that the endpoint implements. YouTrack supports GET, POST, PUT, and DELETE methods.
`path`	The relative path for accessing the endpoint. To use the endpoint in an app, append this path to the name of the handler file and invoke the endpoint via `host.fetchApp()`. Example: `const appResponse = await host.fetchApp('backend/demo', {scope: true});`
`permissions`	The list of permissions to check when someone calls the endpoint with the given method. As long as the user who attempts to access the endpoint has at least one of the specified permissions, the request is authorized. Permissions are listed as an array. Each permission is referenced using its key. For a complete list of permissions and key values, see App Permissions.
`handle`	The function that YouTrack invokes when someone calls the endpoint with the given method.

Scope

Here you can learn more about available scope values for the HTTP endpoints.

Setting the scope guarantees that the scope entity will be available in the context of the handle function.

If you don't set the scope explicitly, the default value is global.

Scope	Description	Related Extension Points
`issue`	Adds the `ctx.issue` entity to the context of the `handle` function.	`ISSUE_ABOVE_ACTIVITY_STREAM` `ISSUE_BELOW_SUMMARY` `ISSUE_FIELD_PANEL_LAST` `ISSUE_FIELD_PANEL_FIRST` `ISSUE_OPTIONS_MENU_ITEM`
`project`	Adds the `ctx.project` entity to the context of the `handle` function.	`HELPDESK_CHANNEL` `PROJECT_SETTINGS`
`article`	Adds the `ctx.article` entity to the context of the `handle` function.	`ARTICLE_OPTIONS_MENU_ITEM`
`user`	Adds the `ctx.user` entity to the context of the `handle` function.	`USER_CARD` `USER_PROFILE_SETTINGS`
`global`	The default scope.	Endpoints with this scope are accessible for all frontend extensions.

HTTP Request

HTTP request is an object (ctx.request) that the endpoint receives.

Properties

Here are the properties of the HTTP request object.

Property	Type	Description
`body`	string	The request body.
`bodyAsStream`	Object	A byte stream representation of the request body.
`headers`	Array.<{name: String, value: String}>	A collection of request headers.
`path`	string	The relative path to the endpoint. Equals `endpoint.path`.
`fullPath`	string	The full path to the endpoint.
`method`	string	The HTTP method that the request used. Can be either GET, POST, PUT, or DELETE.
`parameterNames`	Array.<String>	An array of the URL parameter names

Functions

Here are the functions that you can use to work with HTTP requests.

Property	Return Type	Description
`json()`	JSON	Returns the request body in JSON format.
`getParameter(name)`	string	Returns the URL parameter by its name.
`getParameters(name)`	Array.<String>	Returns all URL parameters by the name as an array of strings.

HTTP Response

The HTTP response is an object (ctx.response) that the handler returns in response to the request from the client.

Properties

Here are the properties of the HTTP response object.

Property	Type	Description
`body`	string	The response body. If an exception occurs during processing, the response body is empty (`null`).
`bodyAsStream`	Object	A byte stream representation of the response body. If an exception occurs during processing, the property is empty (`null`).
`code`	number	The HTTP status code that is assigned to the response. If an exception occurs during processing, the property is empty. 200 by default.

Functions

Here are the functions that you can use to work with HTTP responses.

Function	Return type	Description
`json(object)`		Adds the `Content-Type: application/json` HTTP header to the response that the handler returns to the client. The response is presented in the format of a JSON string.
`text(string)`	string	Adds the `Content-Type: text/plain` HTTP header to the response that the handler returns to the client. The response is presented in the format of a string.
`addHeader(header, value)`	Response object	This function adds an HTTP header to the response. If you pass `null` as the value, the corresponding header will be removed from the response. If you pass more than one header with the same name, only the last one persists.

Requirements

You can include additional requirements for the HTTP handler objects. An HTTP handler object has the requirements field that you may use to define the requirements for the script.

For details about how requirements work for JavaScript scripts in YouTrack in the workflow context, see Requirements.

Accessing Custom REST Endpoints

When you call a custom REST endpoint, you invoke its corresponding HTTP handler. The endpoints used are based on the scope property assigned to the handler.

Scope	URL
`issue`	<host>/api/issues/<issueId>/extensionEndpoints/app/handler/endpoint
`article`	<host>/api/articles/<articleId>/extensionEndpoints/app/handler/endpoint
`project`	<host>/api/admin/projects/<projectId>/extensionEndpoints/app/handler/endpoint
`user`	<host>/api/users/<userId>/extensionEndpoints/app/handler/endpoint
`global`	>host</api/extensionEndpoints/app/handler/endpoint

Set the following variables to match your app:

app — the name of your app.
handler — the name of the file that contains the HTTP handler script in the app package without the .js file extension.
endpoint — the path from the declaration. For example, "path": "/endpoint"

Each API request requires the same permissions as the scope entity. For example, the endpoint /api/issues/DEMO-1/extensionEndpoints/app/handler/endpoint is accessible to any user who has permission to access the issue with the ID DEMO-1. Global endpoints are accessible to all users except the guest account.

Last modified: 19 September 2024