It is my great pleasure to announce the official public beta of RT::Extension::REST2. REST2 is a fundamental rearchitecting of our REST API, which is a set of web services that allows external applications to retrieve and update information in RT. REST2 will let developers build richer and more robust integrations with the other services and applications that your team uses. It is the culmination of four years of work from five engineers, and was driven by the feedback of countless end-users and integration authors.
RT's existing REST API has served its users well throughout the years. REST was added to RT back in 2002 for the 2.1 release series. This was years before AJAX took off thanks to Gmail, and several more years still before Ruby on Rails was first published. At the time, Internet Explorer 6 was still hot off the presses. Needless to say, since then the landscape of the web has changed dramatically. Though RT was an early adopter of REST, back when it looked like SOAP and WSDL were poised to dominate the space, we appreciate that it became time to start anew. The primary consumer is no longer the "rt" command-line application; it is robust integrations with other services and applications.
REST2 was architected for the modern web. It fulfills level 3 of the Richardson Maturity Model. (REST 1.0, on the other hand, meets only level 1). This means that RT expects proper HTTP methods (GET, POST, PUT, DELETE), it provides the full range of HTTP status codes, and RT takes advantage of many HTTP headers in requests and responses (including ETag, If-Modified-Since, etc). We also publish hypermedia controls, which lets your client application explore RT's API dynamically. REST2 has first-class support for JSON which was far and away the most frequent feature request. REST2 was also designed to be extensible. Expect to see additional endpoints and hypermedia materialize as you install extensions.
We are also today releasing a new RT::Authen::Token extension which lets users generate application-specific authentication tokens. This not only makes it easier to get your REST2 application up and running, but it improves security. Your users no longer share their login password, and have the ability revoke an individual application's access.
RT::Extension::REST2 is compatible with RT 4.2.4 and later. You can install it (and RT::Authen::Token, which is compatible with RT 4.2.5 and later) using the ordinary extension installation process. We've also included our REST2 tutorial documentation below to help you hit the ground running.
Finally, while we believe REST2 now provides a stable foundation and a useful set of features—including support for new features in 4.4 like assets, SLA, and custom roles—it is not complete. We are releasing it today to get it into your hands and to hear from you, the developer community, about the features you'd like us to implement next. Please visit our forum thread on REST2 and let us know, either by replying, or just liking an existing message, what you need. All is fair game: anything from additional endpoints such as for articles, to XML support, to additional hypermedia controls, to novel authentication methods, and so on.
We look forward to seeing what you build!
(header photo CC BY Groman123)
REST2 Tutorial
To make it easier to authenticate to REST2, we recommend installing RT::Authen::Token. Visit "Logged in as Username" → Settings → Auth Tokens. Create an Auth Token, give it any description (such as "REST2 with curl"). Make note of the authentication token it provides to you.
For other authentication options see REST2's documentation on Authentication Methods.
Authentication
Run the following in a terminal, filling in XX_TOKEN_XX
from the auth
token above and XX_RT_URL_XX
with the URL for your RT instance.
curl -H 'Authorization: token XX_TOKEN_XX' 'XX_RT_URL_XX/REST/2.0/queues/all'
This does an authenticated request (using the Authorization
HTTP
header with type token
) for all of the queues you can see. You should see a response,
typical of search results, like this:
{
"total" : 1,
"count" : 1,
"page" : 1,
"per_page" : 20,
"items" : [
{
"type" : "queue",
"id" : "1",
"_url" : "XX_RT_URL_XX/REST/2.0/queue/1"
}
]
}
This format is JSON, which is a format for which many programming languages provide libraries for parsing and generating.
(If you instead see a response like {"message":"Unauthorized"}
that
indicates RT couldn't process your authentication token successfully;
make sure the word token
appears between Authorization:
and the auth
token that RT provided to you)
Following Links
You can request one of the provided _url
s to get more information
about that queue.
curl -H 'Authorization: token XX_TOKEN_XX' 'XX_QUEUE_URL_XX'
This will give a lot of information, like so:
{
"id" : 1,
"Name" : "General",
"Description" : "The default queue",
"Lifecycle" : "default",
...
"CustomFields" : {},
"_hyperlinks" : [
{
"id" : "1",
"ref" : "self",
"type" : "queue",
"_url" : "XX_RT_URL_XX/REST/2.0/queue/1"
},
{
"ref" : "history",
"_url" : "XX_RT_URL_XX/REST/2.0/queue/1/history"
},
{
"ref" : "create",
"type" : "ticket",
"_url" : "XX_RT_URL_XX/REST/2.0/ticket?Queue=1"
}
],
}
Of particular note is the _hyperlinks
key, which gives you a list of
related resources to examine (following the
HATEOAS principle). For example an
entry with a ref
of history
lets you examine the transaction log
for a record. You can implement your REST API client knowing that any
other hypermedia link with a ref
of history
has the same meaning,
regardless of whether it's the history of a queue, ticket, asset, etc.
Another ref
you'll see in _hyperlinks
is create
, with a type
of ticket
. This of course gives you the URL to create tickets
in this queue. Importantly, if your user does not have the
CreateTicket
permission in this queue, then REST2 would simply not
include this hyperlink in its response to your request. This allows you
to dynamically adapt your client's behavior to its presence or absence,
just like the web version of RT does.
Creating Tickets
Let's use the _url
from the create
hyperlink with type ticket
.
To create a ticket is a bit more involved, since it requires providing a
different HTTP verb (POST
instead of GET
), a Content-Type
header (to tell REST2 that your content is JSON instead of, say, XML),
and the fields for your new ticket such as Subject. Here is the curl
invocation, wrapped to multiple lines for readability.
curl -X POST
-H "Content-Type: application/json"
-d '{ "Subject": "hello world" }'
-H 'Authorization: token XX_TOKEN_XX'
'XX_TICKET_CREATE_URL_XX'
If successful, that will provide output like so:
{
"_url" : "XX_RT_URL_XX/REST/2.0/ticket/20",
"type" : "ticket",
"id" : "20"
}
(REST2 also produces the status code of 201 Created
with a Location
header of the new ticket, which you may choose to use instead of the
JSON response)
We can fetch that _url
to continue working with this newly-created
ticket. Request the ticket like so (make sure to include the -i
flag
to see response's HTTP headers).
curl -i -H 'Authorization: token XX_TOKEN_XX' 'XX_TICKET_URL_XX'
You'll first see that there are many hyperlinks for tickets, including one for each Lifecycle action you can perform, history, comment, correspond, etc. Again these adapt to whether you have the appropriate permissions to do these actions.
Additionally you'll see an ETag
header for this record, which can be
used for conflict avoidance. We'll first try updating this
ticket with an invalid
ETag
to see what happens.
Updating Tickets
For updating tickets we use the PUT
verb, but otherwise it looks much
like a ticket creation.
curl -X PUT
-H "Content-Type: application/json"
-H "If-Match: invalid-etag"
-d '{ "Subject": "trial update" }'
-H 'Authorization: token XX_TOKEN_XX'
'XX_TICKET_URL_XX'
You'll get an error response like {"message":"Precondition Failed"}
and a status code of 412
. If you examine the ticket, you'll also see
that its Subject was not changed. This is because the If-Match
header
advises the server to make changes if and only if the ticket's
ETag
matches what you provide. Since it differed, the server refused
the request and made no changes.
Now, try the same request by replacing the value invalid-etag
in the
If-Match
request header with the real ETag
you'd received when you
requested the ticket previously. You'll then get a JSON response like:
["Ticket 1: Subject changed from 'hello world' to 'trial update'"]
which is a list of messages meant for displaying to an end-user.
If you GET
the ticket again, you'll observe that the ETag
header now has a different value, indicating that the ticket itself has
changed. This means if you were to retry the PUT
update with the
previous (at the time, expected) ETag
you would instead be rejected
by the server with Precondition Failed
.
You can use ETag
and If-Match
headers to avoid race conditions
such as two people updating a ticket at the same time. Depending on the
sophistication of your client, you may be able to automatically retry
the change by incorporating the changes made on the server (for example
adding time worked can be automatically be recalculated).
You may of course choose to ignore the ETag
header and not provide
If-Match
in your requests; RT doesn't require its use.
Summary
RT's REST2 API provides the tools you need to build robust and dynamic
integrations. Tools like ETag
/If-Match
allow you to avoid
conflicts such as two people taking a ticket at the same time. Using
JSON for all data interchange avoids problems caused by parsing text.
Hypermedia links inform your client application of what the user has the
ability to do.
Careful readers will see that, other than our initial entry into the system, we did not generate any URLs. We only followed links, just like you do when browsing a website on your computer. We've better decoupled the client's implementation from the server's REST API. Additionally, this system lets you be informed of new capabilities in the form of additional hyperlinks.
Using these tools and principles, REST2 will help you build rich, robust, and powerful integrations with the other applications and services that your team uses.