REST2

RT REST2 (JSON) API

• RT has two REST APIs - the original REST v1.0 API and a newer, REST2 JSON API.
• The REST1 API is still used and supported. Many things use it, including RT's mail gateway, rt-mailgate.

The REST2 API uses JSON for queries and responses, making it easier to integrate RT with other systems to read and update RT from scripts and applications on remote servers.

Releases

• The REST2 API was originally provided as extension RT::Extension::REST2 for RT 4.4 and above.

• REST2 is core in RT 5.0.0 and later, so you do not need the extension for those versions.

Authentication Tokens

• It is recommended to use authentication tokens instead of usernames and passwords for API requests, especially when used in scripts and automation. Authentication should always be done over HTTPS/SSL for security. You should only serve up the /REST/2.0/ endpoint over SSL.

• RT 4.4.x requires the extension RT::Authen::Token

• Authentication Tokens is core in RT 5.0.0 and later, so you do not need the extension for those versions.

• If upgrading from RT 4.4.x to RT 5.0.x and later: A clean install is recommended anyway. If you were using RT::Authen::Token. You will need to remove any configuration for RT::Authen::Token and follow the migration steps to migrate your existing tokens to RT5 core.

Documentation and Examples

There are some differences between RT5 core REST2 and earlier RT::Extension::REST2. Refer to the correct documentation for the RT version you are using:

• >= RT 5.0.0: Official REST2 Documentation (latest)
• >= RT 4.4.0: RT::Extension::REST2 Documentation

Unfortunately the documentation lacks detailed explanation and examples in many places, especially for anything other than tickets (users, groups etc.).

The purpose of this wiki page is to collect working examples, code snippets and other resources to help work with the API.

Other sources of help

• Search the RT forums for hints.
• Colloquial posted this very useful OpenAPI Specification. The YAML file describes a lot of the endpoints and parameters. You can use something like Swagger or OpenAPI Generator to generate documentation and client code from this spec. (See below for example)
• RT's test suite files for the REST2 API is also a very useful reference, both for constructing REST2 API requests and the perl API. Locate the test file for the API operation you need, for example to work with users, look in users.t and maybe also user-memberships.t and user-customfields.t. The tests usually create and update objects using the Perl API, then tries to read and manipulate those objects with the corresponding REST2 endpoints and tests for correct responses.

If you can't find an answer:

• Ask in the RT forums for help.
• Try asking ChatGPT or AI tools, referring to the above OpenAPI spec and Documentation.
• Consider alternatives such as the PERL or REST1 APIs.
• Hire Best Practical to develop a solution. :)

Examples

Create New User

curl "$RT_URL/REST/2.0/user" \
   --request POST \
   --header "Authorization: token $RT_TOKEN" \
   --header "Content-Type: application/json" \
   --no-buffer \
   --data-binary '
       {
           "Name": "newuser2",
           "Password": "password123",
           "EmailAddress": "newuser2@example.com",
           "RealName": "New User",
           "Privileged": 1,
       }'

- Omitting Privileged will add an unprivileged user by default.

Get group information

- This example searches for a group "Staff" and returns the details:

curl --silent "<your_server>/REST/2.0/groups" \

   --request POST \
   --header "Authorization: token <your_token>" \
   --header "Content-Type: application/json" \
   --data-binary '
       [
           { "field": "Name",
             "value": "Staff"
            }
       ]'

Response:

{
  "pages": 1,
  "items": [
    {
      "_url": "https://<your_server>/REST/2.0/group/71414",
      "type": "group",
      "id": "71414"
    }
  ],
  "per_page": 20,
  "total": 1,
  "count": 1,
  "page": 1
}

# Add user to group, where group_id is set in a variable.
curl --silent "$RT_URL/REST/2.0/user/$RT_USER/groups" \
   --request PUT \
   --header "Authorization: token $RT_TOKEN" \
   --header "Content-Type: application/json" \
   --data-binary '['$group_id']'

• Working with JSON data structures in bash is fiddly. You can use jq to get values from the JSON in a useable format. For example by piping the above curl command to return various properties from the search for group "Staff"

curl ...<as above> | jq -r '.items[].id'

If you are doing anything serious, it is better to use a scripting language such as python or perl, which has better support for JSON and nested data structures. But by way of example, I have posted a simple example of a bash script to add a user to a group using the REST2 API: rt-groupadd

Clients for RT REST2 API

• python-rt - Python client.

OpenAPI Documentation Generator

• The following example installs and runs openapi-generator on Debian to create documentation based on Colloquial's OpenAPI Specification. There are a number of other ways to install it (see documentation). This was the quickest way for me to install it on my existing RT dev server:

1. Create html directory e.g. /var/www/apidocs and configure your web server to serve this directory from a suitable URL. (optional):

# mkdir /var/www/apidocs

2. nginx config snippet (goes in the relevent server section). restart nginx after adding:

       # REST2 API Docs
       location /apidocs {
               alias /var/www/apidocs;
       }

4. Install:

 # apt-get install pip default-jre
 # pip install openapi-generator-cli

5. Generate docs from yaml, e.g:

 # root@support:~# cd /var/www/apidocs
 # root@support:/var/www/apidocs# wget https://gitlab-ext.utu.fi/rt/request-tracker-openapi/-/raw/main/request_tracker_rest2.yaml
 # root@support:/var/www/apidocs# openapi-generator-cli generate -g html2 -i https://<your_server>/apidocs/request_tracker_rest2.yaml

6. Browse to your documentation location e.g. https://<your_server>/apidocs