Introducing RESTful JSON

Try to imagine a web without links. It’s not easy, as links are the defining feature of the web. They illuminate relationships of information. They give context and meaning to walls of static text. They signify to people or machines what they may or may not do on a given page. A web without links would be no web at all.

Yet, in modern API design, the link has all but disappeared. This is why we‘ve put together RESTful JSON, a minimal and pragmatic design pattern for using links to build expressive and evolvable APIs.

Why the fuss about links?

The power of the link lies in its ability to enliven information, transforming information itself into the means by which humans and computers rationalize what they may or may not do in a given context. As humans, we interact with links on the web as a first-class user interface element by way of clicking and tapping. But implicitly, the presence and absence of these links give us understanding into the current state of the application along with the actions available in that state.

Consider a web page with a login feature. The presence of the login link signifies to a user they are logged out, and they can follow the links to login. Conversely, the presence of a logout link with the absence of the aforementioned login link signifies to the user they are logged in. The user can look at the links to understand the current state without knowing anything about the state logic of the application.

The advantage here is subtle yet substantial. As the user depends on the application to provide the controls at runtime, and as they allow those controls to drive their next interactions with the application, the user relinquishes their need to understand how the application works. It’s why we humans can lose hours at a time following links from Twitter to all over the web without understanding how any of those sites work. We don’t have to understand the entire world in order to interact with it.

Why add links to APIs?

The benefits of links in APIs are no different to the benefits of links we encounter on the web. Links in APIs encourage evolvability and resiliency. An API client that follows links and determines functionality based on the presence and absence of links will be more resilient to change over time. The GitHub API documentation provides a glimpse as to why they include links in their API responses.

These [links] are meant to provide explicit URLs so that proper API clients don’t need to construct URLs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for developers.

GitHub’s hope is that their use of links will make the lives of developers easier over the long term because change will be easier. And GitHub is not the only company adding links—Basecamp, Stripe, Trello, and even Medium include links in their APIs for this reason.

Including links is important because, without links, API clients require more understanding into the inner-workings of the API and hard-coding in order to correctly interact with the information in the API. This results in the duplication of logic in the client and server and tight coupling that is difficult to change as time progresses. Links can help.

The nitty gritty of using RESTful JSON

Against this backdrop on the usefulness of links, let’s explore RESTful JSON. There are only two general rules, which are:

  1. Use a url property to signify a link for an object
  2. Use *_url properties to signify related links to that object

There are no tools you need to do this and no special documentation you must provide for your API consumers other than documenting what links you add. You are even free to modify these rules of RESTful JSON to suit your needs, such as using camel case instead of snake case (e.g. authorUrl instead of author_url). In short, just add links.

Pagination is a good example of where RESTful JSON helps. We’ve probably all seen pagination implementations that require API consumers to add and modify query string parameters to traverse large collections of information. These APIs specify parameters like offset and limit for consumers to define where to start in the results and how many items to return from that start. Consumers then do the math to get each page.

Below is an example of how pagination might work with RESTful JSON. The example includes a link to itself along with a next_url link to the next list of items. It also includes a docs_url that might link to documentation for the current response.

{
"url": "...",
"items": [...],
"next_url": "...",
"docs_url": "http://docs.example.com/books"
}

While there is explicit information here, the links also imply information about the available actions. The absence of the “previous” link tells the consumer they are at the first page, and the presence of the “next” link tells the consumer there are more pages in the collection. Math and pagination logic are not needed to interact with paginated data, just the ability to follow links.

But how does the consumer know it has made it to the end if it’s traversing links? Below is the last page of the paginated results.

{
"url": "...",
"items": [...],
"prev_url": "...",
"docs_url": "http://docs.example.com/books"
}

The absence of the “next” link signifies the end of the collection. Pagination logic on the server may change over time, but clients following links will continue following links.

How to get started with RESTful JSON?

The first step is to check out the documentation to get an idea of the rules and guidelines. Then begin implementing by pragmatically adding links to your API responses where it makes sense. Start removing functionality for building URLs by relying on those new links. Look for functionality that could be deleted in favor of relying on links. Let the link become the way by which the servers drive application state for clients.

As mentioned, RESTful JSON allows for the use of existing tools and technologies. If you’re using the OpenAPI spec (formerly Swagger), API Blueprint, or any other API description format, you can document your links in your models and data structures just like you would any JSON properties. Many API clients like Postman or Insomnia will let you follow links in API responses, which means you allow consumers to browse your API with the tools they already use. And state machine libraries will aid in determining runtime behavior for when a link should be present in an API response.

RESTful JSON is about taking small steps in hopes of yielding evolvability, resiliency over the life of an API. We hope it’s as helpful an idea for you as it has been for us.

Feedback for RESTful JSON is helpful and encouraged. Thanks go out to Mark W. Foster for co-authoring RESTful JSON and providing invaluable feedback for this article. You can find me on Twitter as well.