REST2 Public Beta and Request for Comment


#1

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.

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.

Please see our blog post for more details, including a new token-based authentication method, and an introductory tutorial.

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 let us know, either by replying to this thread, 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.


#2

#3

I’ll throw out the first feature request: search results should include hyperlinks for next/previous paging. That way applications don’t have to manually construct the same request with page+=1 or page-=1. It also means the logic to detect whether you’re on the last page by comparing total against page * per_page is implemented only once: in RT, rather than in each client. Instead, just check for the existence of a hyperlink with a ref of next.

It also opens up the door for more interesting paging mechanisms that avoid items “moving” between pages because of updates to records. Application wouldn’t have to change code, or even restart, to support such a feature.


#4

Feature request: 1) post /group to create a group, so it follows Queue, User and Assett. 2) I’m somewhat unsure if it’s already available, but it would also be nice to be able to set rights on queues and groups through the PUT /queue/:id|:name endpoints.

Doc request; example of post for object creation and put for object update. Or do they simple correspond with the RT-field, so that PUT /queue/1, content: {‘CorrespondAddress’:‘foo@bar.com’} would update the queues CorrespondAddress field?

Also, yey! Improved REST API!


#5

This is wonderful! It makes me ridiculously happy to know that an API for working with Assets is on its way. Thank you Best Practical!


#6

Not sure if this is the right place for this but I created a wrapper for 95% of the new api in Python located on GitHub here. You can also install it with pip install rtapi2. I have not had a chance to test several of the endpoints yet so there may be errors but its available if anyone is interested.

Really glad to see this new API!


#7

It would be great to be able to query a number of fields from a search (e.g. ticket name/status) without having to do a http request per ticket as this makes for very inefficient response.

As far as I can tell, the new REST API does not make possible to achieve, there is no way to retrieve a bulk set of feeds, or request multiple tickets in one request?


#8

Nice job on 2.0. I am close to having a system put into production that will create tickets from sensor alarms that get generated at our gas stations. Pretty basic RT stuff.

Other than the lack of documentation, I’ve just come up with one request. It’s not a show stopper, but a speed improvement.

When I call up an existing ticket, I get the values for my custom fields, but they are only keyed by id. This seems like an odd design. I currently have to go to each custom field URL to find the Name, and then cross reference that id to the values. This causes quite a delay when recalling a ticket. (Although your hyperlink design is very nice.) Could you find a way of getting custom field names into the initial ticket object?

Thanks.


#9

Shawn, that was a great suggestion for adding next/previous page URL’s. I now have a situation that almost demands it.

In a ticket’s JSON there is a _hyperlinks->ref for “history”. Going to that _url, I get a standard JSON search result back, with transaction links for page one. What do I do if there are more than 20 transactions? It’s not obvious on how to retrieve page two, since I didn’t have to supply any parameters. Having these URL’s in the paged result makes a whole lot of sense here.

From ticket data:

‘_hyperlinks’ => [
<…>
{
‘ref’ => ‘history’,
’_url’ => ‘http://localhost/rt/REST/2.0/ticket/1324/history
},
<…>
],

From http://localhost/rt/REST/2.0/ticket/1324/history

  'items' => [
               {
                 'type' => 'transaction',
                 '_url' => 'http://localhost/rt/REST/2.0/transaction/17640',
                 'id' => '17640'
               },
               {
                 'id' => '17641',
                 'type' => 'transaction',
                 '_url' => 'http://localhost/rt/REST/2.0/transaction/17641'
               },
               {
                 'type' => 'transaction',
                 '_url' => 'http://localhost/rt/REST/2.0/transaction/17642',
                 'id' => '17642'
               }
             ],
  'total' => 3,
  'count' => 3,
  'page' => 1,
  'per_page' => 20

#10

Hi,

It would be nice to have the URLs use https and not http. Any remote access would be using that. Now it has to be rewritten everytime. Maybe if the incoming URL is https, return URLs with https and http for an incoming URL with http.

Regards,
Ken


#11

My mistake. The extension already does this. I was using a non-standard HTTPS port and in that case needed to set WebBaseURL appropriately. Sorry for the bother.

Ken


#12

Hey,

My Python dev’s have started using the new REST2 API in anger, and they’re getting a little … angry. :wink: Over all, they really like it. We’re integrating RT with the dashboard for our public cloud offering, so we’re displaying all of a customers tickets in a different interface. This requires many many more requests against the v2 API than the v1 API.

Notable things which we’re missing:

  1. When searching tickets we get the ID & URL for the tickets, but no fields, this is possible with v1.
  2. To get all custom fields, transactions and attachments requires a query per record per record type (and custom fields are identified by id, not name, so you need to lookup the id first)
  3. It seems that the order of the query in the TicketSQL can drastically change the results returned.
  4. They would like to be able use JSON search syntax rather than TicketSQL (I realise this might be a bit of a big change!)
  5. Appears attachments can only be added using the v1 API.

To solve 1 & 2 it’d be great if we could list the fields to return in addition to the id & url for each record and to optionally return data on transactions and custom fields.

I am working to get some examples for 3.

To solve 5 being able to include attachments on a new comment/reply transaction as a multipart encoded form would be ideal.

It’d be good to hear what Best Practical think, as I might be able to get some internal dev time to work on some of these.

Cheers,
Andrew


#13

I’ve created a pull request for a patch I’ve written which adds next/prev links for collection results when appropriate. Also returns the number of pages.


#14

I have a first cut for both 1 & 2, but I want to add a few more features to those before I issue a pull request. For anyone interested they are on this branches on github:

Additional fields:


Make CustomFields easier to use and more consistent with other fields:

It seems that the issue with TicketSQL ordering might be related to not escaping quotes and/or spaces correctly. I was able to accidentally reproduce the issue…


#15

It would be nice to be able to view all the values of a certain custom field. Like, for example, if I have a custom field “Client” with clients’ names and I need to perform some action upon each of the clients, I need to iterate through each of the value of the custom field “Client”, which is at the moment impossible via API.


#16

Hey,

If you’re using a Select, then this pull request might be useful: https://github.com/bestpractical/rt-extension-rest2/pull/2

Otherwise, yeah, a bit more work required…


#17

It would be nice if there was a posibility of grouping and counting. Basically the same functionality as ‘group by’ option in ‘Charts’, but through REST API with a text response.