Although JSON’s compact size and object-friendly nature make it very easy to use as a data representation, it's lack of a standard model schema can prompt some developers to invent different ways for representing complex model relationships in their data. As the complexities of JSON modeling between front-end applications and back-end web servers has increased, so has the advantages of standardizing JSON model representations in web applications. The JSON API standard is a popular way of standardizing how applications interact with REST API response models of API resources. The JSON API format is simply a schema for structuring your model so that its relationships with other data can be represented in a consistent, normalized manner.

Consider our blog post model schema. We have an array of blog posts items, each with an ID as well as a number of attributes, including a nested relationship for the author of the blog post, which has its own ID and attributes:

[{
   id: "123",
   title: "My First Blog Post",
   content: "... brevity is the soul of wit...",
   published “2017-05-28T03:08:25.837Z"
   author: {
     id: "1",
     firstName: "Nicholas",
     lastName: "McClay",
     email: "[email protected]"
   }
 }];

This format is very simple, but what if we had many blog posts and only a few authors? How do we know whether an author is its own model or whether it's simply a nested property of a blog post? How can we distinguish between the ID for blog and the ID for author? These are all problems that JSON API is well suited to handle for us. Let's take a look at how the same model schema would be represented in JSON API:

{
   "data": [{
     "type": "posts",
     "id": "123",
     "attributes": {
       "title": "My First Blog Post",
       "content": "... brevity is the soul of wit...",
       "published": "2017-05-28T03:08:25.837Z"
     },
     "relationships": {
       "author": {
         "data": {
           "type": "authors",
           "id": "1"
         }
       }
     }
   }],
   "included": [
     {
       "type": "authors",
       "id": "1",
       "attributes": {
         "first-name": "Nicholas",
         "last-name": "McClay",
         "email": "[email protected]"
       }
     }
   ]
 }

Clearly, JSON API is a much larger representation of the same REST API response, but it does provide some very powerful advantages in return. One of the first advantages is the clear distinction between identifiers of models and the attributes. The type and id properties inside the data property of our request are used to identify exactly what this model is, independently from its attributes. Conversely, the attributes property only contains the attribute properties for our primary model.

Perhaps the most obvious change is that there is a reference for relationships in our data now. Our author model is now mapped to an included property in the root of our request. This means that, if there were multiple posts in our response that all referenced the same author, we would see only this single model definition for that author. This is very useful for shared services in Angular because it means that we can now cache models independently by type. With a simple model lookup by type and ID, we could easily make a service that could join together data relationships on the front-end without the need to request the entire state of an object and its descendent relationships every time. This can result in improvements to application performance when using cached data and better project maintainability through model normalization.

One final advantage is that data now has a consistent schema when it is transmitted by the REST API. This standard means that we can rely on our data being formatted consistently across our application, which can pay dividends for code reuse and simplicity in our project. All of these advantages combined show the value of standardizing to using JSON API for our REST API.

Let's spend some time digging into how to convert our REST API over to using JSON API.