In the world of API engineering, there is no more hotly debated area than design. From REST, gRPC to GraphQL, there are many ways to design and standardize Web API interactions. Today, we turn our attention to another approach, JSON API, the specification detailed at JSONAPI.org for building APIs.
The JSON API described at JSONAPI.org is great for making your JSON response formats more consistent. Aimed at increasing productivity and efficiency, JSON API is touted for its efficient caching capabilities that can eliminate redundant server requests.
In this article, we'll define what a JSON API is and see how it can be used to build efficient APIs. We'll cover some of the key benefits of the JSON API and see how the specification is used in practice with a case study from FitBit. Hopefully this overview will introduce those new to the JSON API and help you decide if it's the right fit for your API scenario.
What is JSON API (JSONAPI.org)?
JSON API is a format suitable for HTTP. It describes how the client should request or edit data from the server, and how the server should respond to said requests. A major goal of the specification (now stable v1.0) is to optimize HTTP requests; both in terms of number of requests and packet size exchanged between client and server.
"JSON API is a Wire protocol for fetching and updating graphs incrementally over HTTP"
- Yehuda Katz
In JSON API, both client and server send JSON API data in a request document with the following headers, without specifying a media type parameter:
Content-Type: application/vnd.api+json
The JSON API represents how to invoke resources and how to share related links. The JSON object at the root of the request must contain resource data, errors, or meta information. Data and relationships to data can be retrieved with a GET call as follows:
GET /articles HTTP/1.1
Accept: application/vnd.api+json
Here's how the resource type `articles` appears 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" }
}
}
}
// ...Pretty standard stuff so far. The JSON API supports the typical CRUD process of creating, updating, and deleting resources. The JSON API will always be backwards compatible and it is a community driven initiative accepting pull requests on Github.
Benefits of using the JSON API
Now that we have a basic understanding of what a JSON API is, what unique strengths make it stand out?
compound document
Compound documents are a unique feature in the JSON API that allow the server to send related resources along with the main resource requested - which, if implemented properly, can reduce the number of necessary HTTP requests. Compound documents work with include parameters as follows:
GET https://api.example.com/posts?include=author
This enables you to include other resources in the initial request.
sparse fieldset
If you use compound documents to contain related resources, you may experience high response volumes. Once again, JSON API has a solution.
Another unique aspect of JSON APIs is sparse fieldsets, which enable clients to request data only from specific fields. It works by adding the fields to be retrieved to the URI parameters with the resource name and the desired fields. This provides additional customization and can reduce bloat. It looks like:
GET /articles?include=author&;fields[articles]=title,body&;fields[people]=name HTTP/1.1
Accept: application/vnd.api+json稀疏字段集是一种标准化方法，它允许客户端仅指定他们希望从对象中包含在响应中的属性。使用稀疏字段集，您只能获得所需的字段，提供独特的定制潜力，这对精益数据共享环境很有吸引力。
optional
Many features in JSONAPI.org are optional; you can turn them off or on. These features allow customers to decide which resources to accept, which fits well into a lean mobile environment. Having clients agree on how to retrieve and process data is helpful because it removes redundancy and optimizes to reduce bloat.
optimization function
JSON API is equipped with many features to optimize API return packets. Special server-side operations in the JSON API include sorting and paging; the ability to limit the number of returned resources to a subset, including first, last, next, and prev links.
cache
In his talk, Lee highlighted how well-defined resources can improve caching and thus "perceived speed" for end users.
"Because fewer resources are affected by data changes, fewer resources fail when data changes"
In the JSON API use case, caching is inherently built into HTTP. Since clients using the JSON API access the data in the same way, they do not need to store the data in different locations. This design may require a shift in thinking, but when used correctly, can lead to significant optimization benefits.
How the JSON API is Used in Practice: A FitBit Case Study
Let's see how JSON APIs are implemented in practice to design efficient APIs, using a 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. Fitness wearable company FitBit has a thriving API program; 1/4 of its 4 billion annual requests are made through third-party apps, generating significant revenue.
Conforming to the API style helps standardize clients
A common problem is when different client types prefer different methods to retrieve data from the server. Engineering teams formed around functional areas typically implement new functionality incrementally, one platform at a time, and find opposing constraints in each client.
Lee describes how the FitBit team has four main customers: Android, iOS, Windows, and the Web. A major problem is that Android and iOS have very different ideas of how an API should behave. iOS prefers fewer network requests and larger API responses, while Android prefers more network requests and smaller API responses.
To normalize these constraints into a consistent data model, the team must first resolve the debate between request count and request size. The FitBit team works in a mobile environment with hostile data networks and cannot rely on ideal client connections.
Believing in the growing popularity of HTTP/2, TLS 1.3, and improved LTE networks, the FitBit team decided they could reduce the overhead of requests, make concurrent requests, and reduce security latency issues, all while trusting in more resilient connections. This will cause them to use smaller resources and many lightweight HTTP requests.
JSON API helps create a consistent data model
"Without clear guidance, data models can become confusing."
- Jeremiah Lee
Lee describes how at FitBit, their API started to resemble a "view model"; existing endpoints became overloaded, and data dependencies were loose rather than broad in scope. The team is reloading endpoints based on UX views.
As customer experiences evolve over time, teams are splitting data in arbitrary ways. This created a lot of inconsistency as there was no authority or style to follow. The misalignment between the client and server data models created problems. Teams need to agree on how to retrieve and process data, and they need to be able to check for data changes with little overhead.
They tend to use the JSON API to normalize their data. Using the JSON API's ability to define relationships between data, they were able to establish client-server communication expectations.
JSON API helps keep things in sync
Another issue in the FitBit case was keeping up with the server. Their devices need to be frequently synchronized with the server, and this data can also be modified by third-party applications.
These changes must be reflected in all API clients very quickly. HTTP caching leveraged by JSON APIs allows them to prevent the recall of stale data, reducing redundancy and improving end-user perceived speed. According to Lee, it's really starting to layer multiple experiences in one app.
Comparing JSON API and GraphQL
Since we're essentially talking about using graphs, why not GraphQL? While you can achieve many of the same things with GraphQL, Lee sees two main benefits of adopting a JSON API: pagination and cacheability.
Pagination is one area that GraphQL doesn't specifically address. Alternatively, the JSON API provides links such as next and prev to the client when the client requests them. Since pagination in GraphQL is entirely handled by the client, Lee considers this unfortunate because the client could be making expensive, time-consuming database queries without knowing it.
GraphQL also doesn't take advantage of HTTP caching because it's protocol-agnostic. Since there is no recommended general approach, this means that every GraphQL API will handle caching slightly differently.
"I personally think caching is too important for client performance considerations to be an afterthought"
- Jeremiah Lee
Lee also noted that using a JSON API means developers don't have to adopt yet another toolchain like GraphQL, but can continue to use technologies they're likely already familiar with.
Many of the benefits of GraphQL, such as query efficiency and reduced round-trip calls, can be matched in JSON APIs using sparse fieldsets and compound documents. JSON API can thus provide the same functionality as GraphQL.
Consider JSON API for "pragmatic" API design
JSON API Logo Jeremiah Lee calls it "pragmatic," and we have to agree. As mentioned above, there are many advantages to having client and server share a common data model such as a JSON API.
"The JSONAPI.org specification should be your smart default"
- Jeremiah Lee
While the JSON API isn't suitable for every situation, many claim it's a good default way for clients and servers to share a common data interface over HTTP. With the advantages listed above, and its healthy adoption, JSON API seems to be a strong contender for API style.
We encourage you to read the specification yourself. What do you think of JSONAPI.org? What specification do you use to define your API and data model?
| This article : https://architect.pub/benefits-using-json-api | ||
| Discussion: Knowledge Planet [Chief Architect Circle] or add WeChat trumpet [ca_cto] or add QQ group [792862318] | ||
| No public |
[jiagoushipro] [Super Architect] Wonderful graphic and detailed explanation of architecture methodology, architecture practice, technical principles, and technical trends. We are waiting for you, please scan and pay attention. |
|
| WeChat trumpet |
[ca_cea] Community of 50,000 people, discussing: enterprise architecture, cloud computing, big data, data science, Internet of Things, artificial intelligence, security, full-stack development, DevOps, digitalization. |
|
| QQ group |
[285069459] In-depth exchange of enterprise architecture, business architecture, application architecture, data architecture, technical architecture, integration architecture, security architecture. And various emerging technologies such as big data, cloud computing, Internet of Things, artificial intelligence, etc. Join the QQ group to share valuable reports and dry goods. |
|
| video number | [Super Architect] Quickly understand the basic concepts, models, methods, and experiences related to architecture in 1 minute. 1 minute a day, the structure is familiar. |
|
| knowledge planet | [Chief Architect Circle] Ask big names, get in touch with them, or get private information sharing. | |
| Himalayas | [Super Architect] Learn about the latest black technology information and architecture experience on the road or in the car. | [Intelligent moments, Mr. Architecture will talk to you about black technology] |
| knowledge planet | Meet more friends, workplace and technical chat. | Knowledge Planet【Workplace and Technology】 |
| Harry | https://www.linkedin.com/in/architect-harry/ | |
| LinkedIn group | LinkedIn Architecture Group | https://www.linkedin.com/groups/14209750/ |
| Weibo | 【Super Architect】 | smart moment |
| Bilibili | 【Super Architect】 | |
| Tik Tok | 【cea_cio】Super Architect | |
| quick worker | 【cea_cio_cto】Super Architect | |
| little red book | [cea_csa_cto] Super Architect | |
| website | CIO (Chief Information Officer) | https://cio.ceo |
| website | CIOs, CTOs and CDOs | https://cioctocdo.com |
| website | Architect practical sharing | https://architect.pub |
| website | Programmer cloud development sharing | https://pgmr.cloud |
| website | Chief Architect Community | https://jiagoushi.pro |
| website | Application development and development platform | https://apaas.dev |
| website | Development Information Network | https://xinxi.dev |
| website | super architect | https://jiagou.dev |
| website | Enterprise technical training | https://peixun.dev |
| website | Programmer's Book | https://pgmr.pub |
| website | developer chat | https://blog.developer.chat |
| website | CPO Collection | https://cpo.work |
| website | chief security officer | https://cso.pub |
| website | CIO cool | https://cio.cool |
| website | CDO information | https://cdo.fyi |
| website | CXO information | https://cxo.pub |
Thank you for your attention, forwarding, likes and watching.