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:

• data - Contains the Resource itself (or an Array of such Resources)
• included - Contains an Array of other Resources. In the above example, the included data is requested. Additionally, the server may include any unrequested Resources it wants.

Resources themselves have four top-level fields:

• type - A namespace of sorts for all similar Resources, represented as a String. Example: "widgets"
• id - An identifier unique to its namespace, represented as a String. Example: "42"
• attributes - Any properties specific to this Resource, represented as an Object. Example: { "name": "Best Widget Ever" }
• relationships - Links from this Resource to all related Resources, represented as an Object. Each of these values should be a Resource Identifier, an Array of Resource Identifiers, or null. Example: { "brand": { "type": "companies", "id": "Initech" } }.

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

Routes

• You can fetch a resource with a GET request, which will return the complete Resource as described above. Example: GET /widgets
• You can create a resource with a POST request, which should include the complete Resource being created in the request body. Example: POST /widgets
• You can update a resource with a PATCH request, which should include only the attributes and relationships that should be updated, using the structure described above for HTTP entities containing Resources. Example: PATCH /widgets/42
• You can remove a resource with a DELETE request. Example: DELETE /widgets/42
• You can replace a relationship with a PATCH request, which should include the entire relationship being replaced (e.g. a Resource Identifier, an Array of Resource Identifiers, or null) under a data field. Example: PATCH /widgets/42/brand
• You can append to a one-to-many relationship with a POST request, which should include the relationship(s) being appended (e.g. a Resource Identifier or an Array of Resource Identifiers) under a data field. Example: POST /widgets/42/parts
• You can remove from a one-to-many relationship with a DELETE request, which should include the relationship(s) being removed (e.g. a Resource Identifier or an Array of Resource Identifiers) under a data field. Example: DELETE /widgets/42/parts

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.

29th of June, 2016

• Mental Health First

• Speaking Up