New JSON API Specification Aims to Speed API Development

New API specification JSON API was released at the end of May but is already seeing the emergence of an active developer community starring and forking the GitHub repo and building integration libraries and tools.

JSON API was created by Steve Klabnik, Yehuda Katz, Dan Gebhardt and Tyler Kellen, with all issues raised via the GitHub repo and discussed publicly during the specification drafting.

JSON API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests. The JSON API website says the specification has been built in a way to reduce the number of requests and responses that need to be transmitted between client and server “without compromising readability, flexibility, or discoverability.” The JSON API specification is built around the corresponding JSON API media type as the main conduit for exchanging data.

Three of the key goals of creating the specification are to:

  1. Enable developers to speed up API development by using agreed-upon API coding conventions
  2. Future-proof APIs by committing the API design to backward compatibility
  3. Assist dev shops and other instant API creators to avoid what is referred to as “bike-shedding”

1. Speeding up API Development

Speaking recently at APIDays Mediterranea in Barcelona, Spain, Klabnik, a co-creator of the JSON API specification, said that at the moment, “every single way we build APIs is built in its own artisanal, free-range language.” He noted that while they are not completely different (for example, they all use HTML, and most use JSON/XML), and standards bodies like W3C encourage even more API conventions, for dev teams wanting to get started on their API projects quickly, the JSON API format has been designed to help speed up API design and development.

Steve Klabnik presenting JSON API at API Days Mediterranea

Steve Klabnik presenting JSON API at API Days Mediterranea

This approach comes from a Rails legacy, where convention is legitimized over configuration, meaning that developers are encouraged to use the standards established in the JSON API way of doing things rather than writing API protocols based on their specific use cases. As with Rails, this means developers are giving up some control over the way their APIs work, but the payoff is the opportunity to be “ridiculously productive,” Klabnik argued.


Klabnik believes that JSON API will be suitable for around 80% of APIs being created, so some configuration-over-convention cases still exist, but in the main, the spec can help speed up most dev shop-created API projects.

2. Future-Proof API Design

A key feature of JSON API is a commitment to ensuring backward compatibility. One of the biggest pain points for businesses starting on an API strategy is the fear that as they cultivate maturity with their API tactics, they will inevitably break their early efforts as they learn more and seek to build in more features and protocols into their APIs.

JSON API believes it has sorted this problem by committing to a “never remove, only add” strategy in the specification itself, as well as in how developers should utilize the specification.

3. Avoiding Bike-Shedding

One of the main motivations for creating the resource was to help developer teams avoid lengthy arguments over trivial decisions, Klabnik said. He pointed to Parkinson’s law of triviality, which posits that given the choice, people will argue more over a trivial factor rather than the broader scope. In other words, developer teams are more likely to argue over what color to paint a bike shed than the design of the bike shed itself, hence the metaphor bike-shedding. (To demonstrate how easy it is to get caught up in this debate, Klabnik shared that he had wanted to show images of bike sheds for his presentation, but ended up deciding that one of the images found via Web search was not what he would consider a bike shed, thus falling into a meta-metaphor conundrum of bike-shedding about bike-shedding.)

Klabnik pointed out that, often, consultancies and dev shops need to develop APIs for their customers, and by using JSON API, teams can build their API products “without arguing over specifics.”


Full documentation of the JSON API specification includes:

  • Detailed format notes that describe conventions in using the JSON API, including document structure, fetching data, CRUD operations on resources, query parameters and handling errors
  • Experimental, official and custom extensions for JSON API, including support for performing multiple operations in a single request, implementation of JSON PATCH and adding the profile link relation in a JSON API spec
  • Recommendations for using the specification that — while not as official as the formatting convention notes — reflect wider Web services programming paradigms and are suggested so as to provide programmers with a degree of consistency across their other API-related project work
  • Example code
  • A list of implementation libraries for both client and server side and some related tools, such as implementation tools of JSON PATCH for Ruby, Node.js and Python

Other resources include a Google Group, although it appears most issues mentioned in this forum have gone unanswered by the JSON API team to date. A Twitter account shares details of new implementation tools and blog posts about the spec, and the entire JSON API site and specification are managed via GitHub.

Implementation Tools in an Emerging Ecosystem

Already the spec has been starred by 2,403 users (indicating the number of GitHub users who find the repo interesting), has been forked 278 times and is being followed by 138 developers. Ninety-five contributors have worked on the spec to date. Co-creator Gebhardt recently published a blog post outlining the history of designing the API specification.

A number of tools are cropping up showing that devs are willing to build in the JSON API ecosystem. These include:

  • Katharsis: A library to enable creation of hypermedia APIs in Java using the JSON API standard
  • Yayson: A library for serializing and reading JSON API data in JavaScript

The emergence of tools in the ecosystem is a good sign, and JSON API is expected to gain further traction, especially as many developers hold off on even looking at new standards or approaches until they have reached the stability of a version 1.0. How JSON API will compare with devs committed to JSON-LD, HAL and even collection+json formats will be watched closely. For now, one of the shortcomings may be that not all of the features that JSON API provides can be documented in a JSON Schema.

Some may also say that the fact that the JSON API logo is itself not strictly in JSON may be a detracting factor (it is missing the inverted commas in order to look prettier and less busy), but perhaps those complainers are just bike-shedding.

Mark Boyd is a ProgrammableWeb writer covering breaking news, API business strategies and models, open data, and smart cities.