JSON API in 5 Minutes

This is a Resource (from http://jsonapi.org/examples/):

  "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"

HTTP entities that contain a Resource do so with two top-level fields:

Resources themselves have four top-level fields:

Resource Identifiers are, as their name implies, only the identifying properties of a Resource: type and id.


Further Reading

Obviously this just skims the surface of what JSON API is, even going so far as to assume you already know why JSON API is a good idea, or how you would go about making that judgement for yourself.

While I understand that the official documentation contains very precise, technical writing, I cannot overstate how valuable that documentation is for understanding the standard.

As for the "why" of things, I'll echo their supposition that JSON API is a valueable anti-bikeshedding tool; this standard is what most teams work toward when they roll their own API design, and few teams ever make it. Starting from a worked standard like JSON API foregoes this process, enabling teams to develop the model and business logic without worrying about PUT vs PATCH, where to put metadata on a route that returns a POJO, etc.

TL;DR: Go read the official spec.

More Posts