Design guidelines used for the diretto RESTful APIs

During the redesign of the diretto APIs, we focussed on a style that follows more the principles of REST and paid attention to a consistent use of patterns and guidelines for all of our APIs. While some of them are well established, others are rather controversial to some extent in the REST community. This article gives a short overview hereof.

Extensive documentation

Although in theory a single starting URI should be enough to describe a REST API, we wanted to provide extensive documentation for all of our APIs. This not just helps us to keep track of our API features, it also helps developers to getting started with it.

The documentation lists all of the resources, possible representations and operations on these resources. For operations, sample entities as well as a list of possible response codes are listed. The documentation also provides URI template information and authentication requirements.

We developed our own template for creating REST documentations that transforms a XML-based descriptions of an API into a HTML file (or other formats such as plaintext or PDF). All example entities (in our case only JSON) have been validated and formatted, to assure correct and readable snippets.

URI as only ID

Another change was the introduction of URIs as the only way of identifying platform resources. While this is an obvious characteristic of REST, we were still referring to our internal resource IDs in some of our API calls in the previous version. Now we use URIs for everything.

Hyperlinks between resources

A side benefit of the URI-only approach is the increased linking between different resources. When a user creates a resource, it’s representation will not list his name or internal ID as the creator, but it will contain a hyperlink to the user’s URI. By providing useful links to the most important resources on the entry resource, a client can now navigate through the entire platform without having to know any URI pattern or template in advance.

Collection Resources

This is a bit controversial when it comes to URI design, but we decided to differentiate between a resource path prefix and a resource collection path prefix. So when the URI of a resource is /resource/{internal-id}, the corresponding collection resource is /resources. The separation prevents collisions when the collection resource has sub-resources itself.

Pagination using cursors

Our APIs contain a lot of resources that provide lists to other resources. With unbound length, it is not reasonable to return an entire list in a single request. We therefore use pagination to split up these lists. Pagination is done using cursors allowing stateless pages. Each page contains a list of links pointing to the previous and next page as well as the first page of the list. A page is identified by the first hit on the page.

Tags: documentation, json, rest, web service