In the world of API craft, no area is more hotly discussed than design. From REST, gRPC, to GraphQL, there are many approaches to designing and standardizing web API interactions. Today we turn our focus to another approach, JSON API, a specification for building APIs detailed at JSONAPI.org.

JSON API, described at JSONAPI.org, is great for making your JSON response formatting more consistent. With the goal being to increase productivity and efficiency, JSON API has been touted for its efficient caching features that can eliminate superfluous server requests.

In this piece, we’ll define what JSON API is, and see how it might be used to build efficient APIs. We’ll introduce some of the main benefits of JSON API, and also peek into case studies at FitBit to see how this specification has been used in practice. Hopefully, this overview will introduce newcomers to JSON API and help you gauge if it’s a right fit for your API scenario.

What Is JSON API (JSONAPI.org)?

JSON API is a format that works with HTTP. It delineates how clients should request or edit data from a server, and how the server should respond to said requests. A main goal of the specification (now at a stable v1.0) is to optimize HTTP requests; both in terms of the number of requests and the size of data packages exchanged between clients and servers.

“JSON API is a wire protocol for incrementally fetching and updating a graph over HTTP”
–Yehuda Katz

In JSON API, both clients and servers send JSON API data in request documents with the following header without specifying media type parameters:

Content-Type: application/vnd.api+json

JSON API denotes how resources are called and how associated links are shared. A JSON object is at the root of requests, which must include either resource data, error, or meta information. Data, and also relationships to data can be fetched through GET calls like such:

GET /articles HTTP/1.1
Accept: application/vnd.api+json

Here’s how a resource type `articles` may appear in a JSON API response:

// ...
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "/articles/1/relationships/author",
        "related": "/articles/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  }
}
// ...

So far, pretty standard stuff. JSON API supports your typical CRUD processes for creating, updating, and deleting resources. JSON API will always be backwards compatible, and it’s a community-driven initiative accepting pull requests here on Github.

Benefits From Using JSON API

Now that we have a basic idea of what JSON API is, what are some unique benefits that make it stand out?

Compound Documents

Compound documents is a unique ability in JSON API, allowing servers to send related resources alongside the requested primary resources — if implemented correctly this could decrease the number of necessary HTTP requests. Compound documents works by using the include parameter like as follows:

GET https://api.example.com/posts?include=author

This enables you to include additional resources in an initial request.

Sparse Fieldsets

If you’re using compound documents to include related resources, you could run into an issue of having large responses. Once again, JSON API has a solution.

Another unique aspect of JSON API are sparse fieldsets, which enable clients to only request data from specific fields. It works by adding the field you want to retrieve to the URI parameter with the resource name and the fields you want. This offers additional customization and can decrease bloat. It looks something like:

GET /articles?include=author&;fields[articles]=title,body&;fields[people]=name HTTP/1.1
Accept: application/vnd.api+json

Sparse fieldsets is a standardized method of allowing clients to specify only the properties they want from an object to be included in the response. Using sparse fieldsets, you get only the fields that you desire, offering unique customization potential that is alluring for lean data sharing environments.

Optionality

Many of the features in JSONAPI.org are purely optional; you can turn them off or on. The features give the clients the power to determine what resources to accept, lending well to lean mobile environments. Getting clients to agree on how to retrieve and handle data is helpful as it erases redundancy and optimization to reduce bloat.

Optimization Features

JSON API comes equipped with many features to optimize the API return package. Special server side operations in JSON API include sorting, as well as pagination; the ability to limit the number of returned resources to a subset, with first, last, next, and prev links.

Caching

In his presentation Lee emphasized how well-defined resources can improve cacheability, resulting in an increase in “perceived speed” for end users.

“Because data changes affect fewer resources, there are fewer resources invalidated when data changes”

In JSON API use cases, caching is in essence built into HTTP. Since clients using JSON API access data in the same way, they don’t need to store data in various locations. This design may require a shift in thought, yet if used correctly can bring significant optimization benefits.

How JSON API Is Used in Practice: FitBit Case Study

Let’s see how JSON API has been implemented in practice to design efficient APIs, using FitBit as a real life case study.

Jeremiah Lee led API development at FitBit for 4 years, during which time he was involved in their JSON API adoption. FitBit, the fitness wearable company, has a thriving API program; out of 4 billion annual requests, ¼ of them are through third party applications, amounting to a significant revenue.

Conforming API Style Helps To Standardize Clients

A common problem is when different client types prefer different methods on how to retrieve data from the server. Engineering teams formed around feature areas often implement the new feature gradually one platform at a time, and find opposing constraints in each client.

Lee described how the FitBit team had four major clients: Android, iOS, Windows, and Web. A main problem was that Android and iOS had very different ideas on how the API should function. Whereas iOS prefered fewer network requests with large API responses, Android preferred more network requests with smaller API responses.

In order to normalize the these constraints into a consistent data model, the team had to first resolve the debate between number of requests and the size of request. Working in a mobile setting with hostile data networks, the FitBit team couldn’t rely on ideal client connections.

Putting faith in growing adoption of HTTP/2, TLS 1.3, and improved LTE networks, the FitBit team resolved that they could reduce the overhead of requests, make concurrent requests, and reduce security latency issues, while at the same time putting faith in more resilient connections. This would lead them to adopt smaller resources and many lightweight HTTP requests.

JSON API Helped Create Consistent Data Models

“Without clear guidance, data models can become messy.”
-Jeremiah Lee

Lee describes how at FitBit, their APIs began to resemble “view models;” existing endpoints were becoming overloaded, and the data was loosely related instead of well-scoped. The teams were overloading endpoints based on user experience views.

As the client experience evolved over time, the teams were splitting data in arbitrary ways. With no authority or style to follow, this created much inconsistency. Misalignment between client and server data models was creating problems. The team needed to agree on how to retrieve data and handle data, and needed the ability to check for data changes with little overhead.

They gravitated toward JSON API to normalize their data. Using JSON API’s ability to define relationships between data, they were able to establish client-server communication expectations.

JSON API Helps Stay in Sync

Another issue in FitBit’s case was staying in sync with the server. Their devices need to sync often with the server, and that data can also be modified by third party applications.

These changes must be reflected across all API clients very quickly. The HTTP caching leveraged by JSON API enabled them to prevent recalling stale data, thus reducing redundancy and increasing the perceived speed for end users. According to Lee, this really starts to add up across multiple experiences within an application.

Comparing JSON API to GraphQL

Since we’re essentially talking about working with a graph, why not use GraphQL? While you can achieve many of the same features using GraphQL, Lee sees two major benefits of JSON API adoption: pagination and cacheability.

Pagination is an area that is not specifically addressed by GraphQL. Alternatively, JSON API provides links like next and prev to the clients when they request them. Since pagination is entirely handled by the client in GraphQL, Lee finds this is unfortunate, as clients could unknowingly make expensive, time-intensive database queries.

GraphQL also does not leverage HTTP caching features because it’s protocol agnostic. Since there is not a suggested common approach, this means that every GraphQL API will handle caching a little differently.

“I personally believe that caching is too important of a client performance consideration to be an afterthought”
-Jeremiah Lee

Lee also notes that using JSON API means that developers don’t have to embrace another toolchain like GraphQL, but can continue using technologies they are most likely already familiar with.

Many of the benefits of GraphQL, such as query efficiency and reduction of roundtrip calling, can be matched in JSON API using sparse fieldsets and compound documents. JSON API can thus provide the same sort of functionality found in GraphQL.

Consider JSON API For “Pragmatic” API Design

Jeremiah Lee calls it “pragmatic,” and we have to agree. As evidenced above, there are many advantages to having clients and servers share a common data model like JSON API.

“The JSONAPI.org specification should be your smart default”
– Jeremiah Lee

While JSON API isn’t fit for every situation, it’s purported by many as a great default way for clients and servers to share a common data interface via HTTP. With the advantages listed above, as well as its healthy adoption, JSON API appears to be a strong contender for API style.

We encourage you to read the specification for yourself. What do you think of JSONAPI.org? What specification are you using to define your APIs and data models?

Resources

• Jeremiah Lee Slides with commentary
• Introduction to the JSON:API spec: Presentation by Marco Otte-Witte
• JSON API Homepage
• JSON API Specification
• JSON API Twitter
• JSON API Github
• JSON Patch: Can be used for incremental udpates

Disclaimer: Jeremiah Lee no longer works at FitBit, and the insights he shared at the Platform Summit 2017 were graciously provided to give context to JSONAPI.org. They don’t resemble any official positions taken by FitBit or Spotify.