Developer Portal for YouTrack and Hub Help

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: 7 October 2024