RESTful APIs are becoming a central feature for many projects, and the JSON API specification provides a great resource for developers looking to construct a modern API. Dan Gebhardt, one of the editors of the JSON API specification, has taken some time to answer a few questions on the features and future of JSON API.
What benefits does JSON API provide over other standards like Collection+JSON, HAL, JSON-LD and SIREN?
JSON API's goal is to provide solutions to a broad range of API design problems, freeing developers to focus on the design of their application.
JSON API defines both a media type and protocol usage requirements. In other words, it not only specifies a format for representing resources, it also defines expectations for how to use HTTP to fetch and modify those resources. Of the standards listed, only Collection+JSON attempts to do the same, but its scope is limited to basic CRUD operations. JSON API goes further and specifies how to sort, filter, and paginate collections, request the inclusion of related resources, and modify not only resources but relationships between resources.
JSON API's format and protocol requirements are designed with the goal of minimizing the size and number of requests. For instance, JSON API specifies how to request compound documents, which include primary and related resources together to save the need for N+1 requests. And unlike HAL, which supports embedding of related resources, JSON API requires that each resource be represented only once in a document, which reduces transmission size and processing complexity.
One caveat to adopting JSON API is that it can't typically augment an existing API, unlike JSON-LD which only requires the addition of prefixed keywords to responses. However, because of JSON API's comprehensive scope, your implementation will attain a level of consistency not required by other specifications. Furthermore, you'll be able to take advantage of a growing ecosystem of tools to help you both serve and consume JSON API.
What has the community reaction to JSON API been like?
When JSON API finally reached version 1.0 in May, the community was both relieved and excited. The spec was under very heavy, and very public, development for the prior two years. During this period, many developers were using JSON API more as a set of guidelines than a complete spec, which is understandable given the frequent changes. This churn ended with 1.0, which came with a commitment to stability by allowing only additive changes in the future. A stable spec has enabled an ecosystem of libraries that support it to grow to cover many languages and frameworks. And of course it's exciting to hear from application developers using the spec.
When can developers expect the release of version 1.1?
After we released version 1.0, the primary editors (Yehuda Katz, Steve Klabnik, Tyler Kellen, Ethan Resnick, and myself) decided to commit to a rolling schedule of releases, which would include a temporary beta period during which library implementors could provide feedback on changes. Our initial plan of quarterly releases has proven too ambitious, given the scope of what we're trying to accomplish in version 1.1. We'd like to finalize support for extensions and to start with an extension that supports bulk operations. Since both additions are still in flux, version 1.1 is still forthcoming. We hope to have something to announce soon and will of course still provide a beta period before any additions are rolled into the stable spec.
How do you see developers making use of the upcoming official support for extensions in JSON API?
This is very much an open question that we're currently exploring. The structured format of JSON API documents allows for extension in many places because API-specific (i.e. user-defined) keys are tightly constrained to specific objects. We'd like to allow lightweight extensions that can enable custom additions to this structure. Ethan has recently put forward a proposal for profile extensions that would allow this.
We've also explored different extension negotiation mechanisms in the past based on media type parameters, but ultimately removed this pre-1.0. Although negotiation would ensure that server and client agree on the contract defined by an extension, we need to decide just how comprehensive in scope extensions can be.
What are your favorite tools, tutorials, books or videos on JSON API?
I wrote a post about JSON API 1.0, which includes an overview of the spec, its journey to 1.0, and a vision for its future.
The spec is still young, but I'm looking forward to more resources being available soon. If you'd like to learn more, read the spec and head over to the JSON API forum with your questions.