Writing an API? Think {json:api}

API: Application Programming Interface JSON: JavaScript Object Notation

We use API and JSON a lot these days. It is very difficult to imagine software development without both of these. APIs and JSON are a very integral part of any product. The majority of apps/products we use are having some or other API in the background and data that we pass among systems, well, most of those are JSON.

What Is {json:api}?

JSON:API is a specification for building APIs in JSON.

JSON:API talk about making shared conventions to increase productivity, to take advantage of generalized tooling, and to focus on what matters: your application.

There are very excellent examples available on its website explaining the usage. Here we will try to walk through why do we need such standards and when is it beneficial to use them.

Why Do We Need {json:api}?

Let us take an example to understand the problem {json:api} is trying to address.

When we have a meal, what do we have it in? A plate, a bowl? What will we use to eat it? A spoon, a fork, Chopsticks? Choices are endless but we prefer a different set of utensils based on what type of meal we are consuming. A bowl for soup, a plate for sandwiches.

Now say you are running a cafeteria which serves different items on different days. On average you need to have 1000 serving utensils per day. What will you prefer you serve on? A plate, a bowl? Say you pick a plate and get 1000 of those. Now one day you plan to serve soup as well. Well, you can not use a plate for that. You need to get a bowl for that. Now you have 1000 bowls and 1000 plates. Plus now you have to manage 2 different types of utensils that need different cleaning and storage space. What works for plates, may not work for bowls.

As you grow the business it comes difficult to manage inventory, cleaning, maintaining, etc. Managing the in-house dining set and managing the cafeteria dining set is a very different game. We can not play both games with the same rules and strategies. For the cafeteria, we use fix shaped Compartment Trays. This may not be the best fit for a meal served, but it becomes very easy for the cafeteria to manage it.

Let us take the same analogy to APIs. When we have a few APIs, it is easy to manage different formats for different APIs. When we grow into a much more complex structure it becomes difficult to manage.

When Do We Need {json:api}?

With many applications, products moving to API-driven architecture, or the API-First Approach to Building Products, it becomes very important to know how clients and servers will talk to each other.

When we start with the first API, we may not be worried about what it will grow into or what will be the impact when we change something in the future, but it is very much needed to think this through.

If you are writing an API for an app or a product that does not have too much API-dependent architecture, a small project, or initial POC for some idea, it is okay to not consider {json:api}. But, if you are an organization moving into microservice or a new project with an API-First Approach, it is essential that you consider using {json:api} like convention from the start. You may not feel the need for such a thing at the start but later on, managing multiple response formats and parsing logic becomes a headache and a new problem in itself. You may have picked APIs as a solution to a certain problem but you may end up with another set of problems with managing a large number of different structures of responses.

Basic Request and Response

Request

GET /articles?include=author HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John",
        "age": 80,
        "gender": "male"
      }
    }
  ]
}

More examples available at JSON:API examples

JSON:API provides much more than formating. You can read The Benefits of Using JSON API by Bill Doerrfeld and JSON API: Your smart default by Jeremiah Lee. I would suggest going through examples on JSON:API to get a more clear understanding of the topic.

Adapt before it is too late.