Brief Introduction to the JSON API v1 Specification

JSON API provides a systematic method of specifying Level 3 REST APIs in JSON. It has a registered hypermedia type of application/vnd.api+json issued by the Internet Assigned Numbers Authority (IANA). The next list briefly enrolls the most salient features and benefits of JSON API (see my book Creating Maintainable APIs for more information):

• It is a hypermedia-driven conventional interface: This is a fundamental difference between JSON API and other pure message formats. The JSON API, besides establishing a shared convention regarding message formats, also encompasses rules for how to interact with services (it specifies an assumed API). For example, JSON API contains instructions on how services should fetch, create, update, and delete resources, specify pagination, pass query parameters, and so on. This trait of JSON API is tightly related to the concept of openness in distributed systems. An open distributed system mandates certain rules regarding how services should be implemented and interconnected. This is crucial from the viewpoint of systems interoperability.
• Enables generalized tooling support: JSON API is buttressed with many client and server side frameworks for multitude of programming languages. All of them speak the same underlying messaging protocol and leverages the same API for working with resources.
• Actively promotes the Open/Closed design principle: With JSON API, distributed services can be realized as reusable, independent, and self-contained entities. They should be easily composed without a need to alter them; this is how they would become open for extension and closed for modification.
• Increases the productivity of teams: Members of the team should learn a single standard for message payloads, associated APIs, frameworks, and tools. Integration efforts are also enhanced, since teams (especially when they are geographically distributed) have an agreed upon convention on how to structure their messages, and APIs.
• Increases performance: Services built around JSON API can circumvent data transfer overheads by efficiently caching resources.
• It is inherently a JSON format.

JSON API Specification

The next figure shows the major constituent elements in the JSON API specification (it comes with a JSON Schema to govern content validation). The REST endpoints are implicitly defined based upon the resource's or relationship's properties. For example, the mandatory type and id attributes uniquely identify the resource, hence the endpoint to access it would be http(s)://<host>/<type>/<id>. The figure below was produced with the JSON Editor.

Example Usage of the JSON API

To make this section more comprehensible, we will see how to encode a small power network into JSON API. We will assume that the resources are served by a fictitious service, that speaks JSON API. The figure below shows the portion of the power grid, that we would like to handle. It is simplified network diagram with the corresponding model classes in abbreviated form.

Let us fetch a JSON API document containing basic data about a substation. This data should include information about bays. A substation can contain multiple bays, and usually it is impossible to predict whether a client will always want to receive these when requesting a substation. Therefore, it is left to a client to explicitly ask for an inclusion of bays in a response. A bay is a container for grouping equipment connected in some predefined manner. Inside a typical substation, you will encounter many instances of bays, but most of them are of the same type. In other words, the number of topologically different bays is not that big. Using bays could reduce the complexity of a network, hence, they are kind of an abstraction to reason about a power grid.

A client needs to create the following HTTP request (notice the usage of the include parameter), where the type is substations, and the identifier is Substation_01:

GET /substations/Substation_01?include=bays HTTP/1.1
Accept: application/vnd.api+json

The server should return the following response (the version may be 1.x):

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

{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "http://example.com/substations/Substation_01?include=bays"
  },
  "data": {
    "type": "substations",
    "id": "Substation_01",
    "attributes": {
      "IdentifiedObject-name": "HV/MV 1"
    },
    "relationships": {
      "member-of": {
        "data": { "type": "companies", "id": "Company_01" }
      },
      "bays": {
        "links": {
          "self": "http://example.com/substations/Substation_01/relationships/bays",
          "related": "http://example.com/substations/Substation_01/bays"
        },
        "data": [
          { "type": "bays", "id": "Bay_01" }
        ]
      }
    }
  },
  "included": [{
    "type": "bays",
    "id": "Bay_01",
    "attributes": {
      "IdentifiedObject-name": "Breaker Bay"
    },
    "relationships": {
      "member-of": {
        "data": { "type": "substations", "id": "Substation_01" }
      }
    },
    "links": {
      "self": "http://example.com/bays/Bay_01"
    }
  }]
}

Notice that the other associated equipment (power transformer, breaker, etc.) is not included here, because a client only asked for inclusion of bays. To also include a power transformer a client would need to issue the next request:

GET /substations/Substation_01?include=bays,power-transformers HTTP/1.1
Accept: application/vnd.api+json

Relationships may be directly accessed by augmenting the resource URL with the name of the desired relationship (like, /relationships/<name>). It is also possible to only fetch a partial view of the resource by enumerating the required attributes. Finally, the JSON API provides a well-defined mean to return error information, which is many times left underspecified.

Conclusion

JSON API relieves you from worrying about things that are not essential to your application. It offers a set of conventions, rules, and principles in designing your API. All you need to do is decide what your API should provide in terms of system requirements. JSON API is a mature standard, at the time of this writing the latest version is 1.1. A crucial benefit of using this specification is that it guarantees backward compatibility whilst being evolved and new features added. JSON API also comes with a rich set of client libraries.