A new JSON API specification has been released with the aim of speeding up API development.

The JSON API lays down the rules for the way requests for resources should be phrased, both in terms of the way the client should request resources to be fetched or modified, and how the server should respond to the request.

The idea is that this will reduce the number of requests and responses that need to be transmitted between client and server without compromising readability, flexibility, or discoverability. Features such as compound documents, sparse fieldsets, and multi-field sorting mean clients can request exactly the data they need from a server.

The API defines both a media type (application/vnd.api+json) and rules for the usage of HTTP to fetch and modify resources represented by that media type. The developers of the API have focused on hypermedia, and you can use the JSON API to build hypermedia APIs.

Writing about the new API on the Cerebris blog, Dan Gebhardt (one of the co-creators of the API) said that links can be added throughout JSON API documents to specify canonical URLs for resources and their associated relationships and that clients can "crawl" links in an API just as your browser crawls links in HTML.

He comments:

'By eliminating the need to hard-code URLs (or the logic to derive them), clients and servers become more loosely coupled and can more easily evolve’.

Gebhardt created the JSON API along with Steve Klabnik, Yehuda Katz, and Tyler Kellen.

The base JSON API specification provides conventions for pretty much all the API design details, including aspects such as representing singular resources vs. resource collections; identifying resources; representing relationships between resources; fetching, creating, updating, and deleting resources and relationships; and creating hypermedia links for resources, relationships, and paginated collections.

Alongside the obvious time saving advantages, the creators of JSON API point out that an ecosystem of JSON API compliant libraries that span many languages and frameworks is actively being developed.

Of course one of the dangers is that JSON used to be such a simple and direct way to exchange data and this was one of the main reasons it triumphed over alternatives such as XML and SOAP. Let's hope it doesn't get too complicated in the future.

The intention is to extend the specification to add extra capabilities.  If you want to be involved the project is on GitHub.

Comments

Make a Comment or View Existing Comments Using Disqus

or email your comment to: comments@i-programmer.info