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:
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 YouTrack supports the following scopes: Default value: 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 Example: |
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 |
|
project | Adds the |
|
article | Adds the |
|
user | Adds the |
|
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 |
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 ( |
bodyAsStream | Object | A byte stream representation of the response body. If an exception occurs during processing, the property is empty ( |
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 |
text(string) | string | Adds the |
addHeader(header, value) | Response object | This function adds an HTTP header to the response. If you pass |
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.