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.
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.
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.
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?
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.
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?
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?
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.
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.
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.
My Python devâs have started using the new REST2 API in anger, and theyâre getting a little ⌠angry. 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:
When searching tickets we get the ID & URL for the tickets, but no fields, this is possible with v1.
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)
It seems that the order of the query in the TicketSQL can drastically change the results returned.
They would like to be able use JSON search syntax rather than TicketSQL (I realise this might be a bit of a big change!)
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.
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.
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âŚ
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.
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.
Itâd be great to hear from Best Practical about the feedback on this topic. Iâve issued a few more pull requests for the work Iâve been doing, Iâd love to hear feedback on those, and the pull requests from others as well.
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.