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, ornull
. 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, ornull
) under adata
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 adata
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 adata
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