JSON API Cheatsheet

The JSON API specification the following design goals:

• Standardising the JSON schema (irrespective of the data you’re transmitting)
• Minimising the number of client requests
• Minimising the amount of data transmitted

Understanding how each is achieved is essential in effectively using its features.

The following is a reorganisation and summary of the full specification: https://jsonapi.org/

General requirements

Design Goal: Standardised schema

Object shapes:

• Top-level schema
• Resource Object
• Resource Identifier object
• Linkage Object
• Relationship Object

Consistent top level schema

The top-level schema of responses is the same, regardless of whether a collection, singular item or (possibly) no data is being returned

Client / Request

Nothing explicit; client needs to parse or deserialize the response to get it in a format that is easy to extract information from (JSON API is optimised for data transmission, not retrieval of information).

Server / Response

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "links": {
      "self": "http://example.com/articles/1"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "first-name": "Dan",
      "last-name": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}

Consistent data objects

Client / Request

Nothing explicit; client needs to parse or deserialize the standard object shapes.

Server / Response

The schema comprises of two object types:

• Resource objects: Contain the full list of attributes to represent a resource
• Resource identifier objects: Contain only the necessary information to identify a resource (for linking or requesting the resource object later on)

Resource object vs resource identifier object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// Resource object:
{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      // ... this article's attributes
    },
    "relationships": {
      // ... this article's relationships
    }
  }
}

// Resource identifier object:
{
  "data": {
    "type": "articles",
    "id": "1"
  }
}

Resource object

Hyperlinked media: Standard way of navigating between data

Client / Request

Nothing explicit; client needs to find and use the most appropriate link

Server / Response

links: Can include links to navigate pages, to reload self or to fetch associated data

• Provides easy navigation by including URLs for each request the client may wish to make next, in the current response

Abstract relationships: Standard way of representing all relationships, regardless of implementation

Client / Request

Nothing explicit; client needs deserialize the response and match up included data with its parent using the relationships

Server / Response

data.relationships: Abstracts the details of how items are associated (join tables, foreign keys, etc) and just returns the associated data * Only contains primary keys and data types - for the other attributes, you need to (request and) match up with the data in the included

Relationships are treated as their own entity, allowing endpoints for interacting on the relationship rather than the related resource

Example: author relationship includes

• Link for the relationship itself (allows the client to change the related author directly)
• Related resource link to fetch the resource objects
• Linkage information.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// ...
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "http://example.com/articles/1/relationships/author",
        "related": "http://example.com/articles/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  },
  "links": {
    "self": "http://example.com/articles/1"
  }
}
// ...

Relationships object schema

Standard error reporting

Client / Request

Client needs to deserialize the response and handle the errors

Server / Response

errors: Generalised error reporting that can account for one or more errors occurring

Error schema:

• id Unique identifier for this particular occurrence of the problem
• links Links object containing the following members
• about: a link that leads to further details about this particular occurrence of the problem.
• status HTTP status code applicable to this problem, expressed as a string value.
• code application-specific error code, expressed as a string value
• title short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
• detail human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
• source Object containing references to the source of the error, optionally including any of the following members:
  • pointer: a JSON Pointer [RFC6901] to the associated entity in the request document [e.g. “/data” for a primary data object, or “/data/attributes/title” for a specific attribute].
  • parameter: a string indicating which URI query parameter caused the error.
• meta meta object containing non-standard meta-information about the error

Server can either stop processing as soon as a problem is encountered, or continue and encounter multiple problems

• The most generally applicable HTTP error code should be used in the response

Design Goal: Minimise number of requests

Compound Documents: Including related data client needs

Client / Request

include query parameter: Comma-separated list of relationship paths (dot-separated list of relationship names)

1
2

GET /articles/1?include=comments.author HTTP/1.1
Accept: application/vnd.api+json

Client is required to re-assemble the connections using the primary fields and types in relationships and plucking them out of the included array * Just a flat list - have to match up where they should be nested by finding the matching resource identifier object

Server / Response

Adds a flat, normalised (duplicates removed) array of associated resources in the included attribute

• Response is called a “compound document” (consists of more than just the primary resource requested)
• Note: query param is named include while attribute is named included

Server may return resources related to the primary data by default and may also support an include request parameter to allow the client to customize which related resources should be returned

• Server must remove all default included and only use those specified, if the client is using the query parameter

Because compound documents require full linkage (every included (full) resource object must be referenced by a resource identifier object somewhere else in the document), intermediate resources in a multi-part path must be returned along with the leaf nodes.

• Exception: when relationship fields that would otherwise contain linkage data are excluded via sparse fieldsets (see below).
• Server may choose to expose a deeply nested relationship as a direct relationship with an alias such as comment-authors for comments.author
• would allow a client to request /articles/1?include=comment-authors instead of /articles/1?include=comments.author
• Server can still provide full linkage in compound documents without including potentially unwanted intermediate resources.

Applies to all request types: a server could support the inclusion of related resources along with a POST request to create a resource or relationship

Metadata: Including summary and other metadata

Client / Request

Included by default - up to the server to implement.

Server / Response

meta attribute for things like counts and modified dates, so don’t have to request all results to generate aggregate or summary information

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "meta": {
    "copyright": "Copyright 2015 Example Corp.",
    "authors": [
      "Yehuda Katz",
      "Steve Klabnik",
      "Dan Gebhardt",
      "Tyler Kellen"
    ]
  },
  "data": {
    // ...
  }
}

Design Goal: Minimise amount of data transmitted

Query parameters quick reference

Filtering: Restricting results based on criteria

Client / Request

filter query parameter is reserved for filtering data, but doesn’t tell you how to use it: (implementation agnostic, so can use any filter implementation/algorithm)

• Usually involves specifying multiple filters using the square brackets syntax: filter[name]=foo&filter[age]=21

Server / Response

data:

• Collections: Filters items in the primary document
• Items: Filters the scope for looking up the item (may result in 404 Not Found)

Sorting: Ordering results

Client / Request

sort query parameter is used for filtering

• Recommended dot-separated sort fields be used: E.g. author.name could be used to request that the primary data be sorted based upon the name attribute of the author relationship
• However, fields do not necessarily need to correspond to resource attribute and association names

Sort fields are applied in the order specified

1
2

GET /people?sort=age,name HTTP/1.1
Accept: application/vnd.api+json

Sort fields are ascending unless it is prefixed with a minus

1
2

GET /articles?sort=-created,title HTTP/1.1
Accept: application/vnd.api+json

Server / Response

data:

• Collections: Changes the order of items in the primary document
• Items: No effect

Server may apply default sorting rules to top-level data if request parameter sort is not specified.

Pagination: Truncating data into pages

Client / Request

page query parameter is reserved for pagination, but doesn’t tell you how to use it: (implementation agnostic, so can use any pagination strategy: page-based, offset-based, cursor-based)

• Eg. page[number] and page[size], an offset-based strategy might use page[offset] and page[limit], while a cursor-based strategy might use page[cursor]

Server / Response

data:

• Collections: Truncates the full set of results in the primary document into pages
• Items: No effect

meta: Not dictated, but there are examples of it being used to store the total number of results

included: Server may also paginate included resources

links: If they server does provide pagination, need to include pagination links: first, last, prev, next

• Can be omitted or be null if they’re unavailable
• Placed at the top level or in the included resource they relate to

Sparse fieldsets: Selectively including data client needs

Client / Request

fields query parameter used for specifying a whitelist of attributes to include by specifying a fields[TYPE] parameter.

• Comma separated list
• Empty value indicates that no fields should be returned.

Example:

1
2

GET /articles?include=author&fields[articles]=title,body&fields[people]=name HTTP/1.1
Accept: application/vnd.api+json

Server / Response

If a client uses sparse fieldsets, server must not send back any others

• If not used, server may send all fields, a subset of fields, or no fields for that resource type.

included / relationships: Lifts the requirement of full linkage if the relationship fields that would otherwise contain linkage data are excluded via sparse fieldsets.

Working with primary resources (CRUD)

Viewing a resource

Server / Response

Server must actually implement any routes mentioned in self and related

The data attribute of a response must be a (possible empty) array of resource objects or resource identifier objects for collections, and a resource object or null for a singular item.

General (For Creating, Updating and Destroying)

Request must completely succeed or fail (in a single “transaction”). No partial updates are allowed.

If the client somehow does not have the most up-to-date and complete set of values, the server must respond with the full document again

Examples:

• If using client-generated ids which are ignored and replaced with server generated ones (client needs to be told actual ids used)
• If not using client-generated ids (client needs to be told ids used)
• If updating or creating some attributes, which cause others to be updated or have defaults set (client needs to be told full set of new values)

If the server responds with 204 No Content, client should assume it already has the complete and most up-to-date values for a resource

Creating a resource

Client / Request

Server may accept a client-generated ID along with a request to create a resource, but they must be a universally unique identifier (ideally a properly generated and formatted UUID as described in RFC 4122)

Server / Response

Updating a resource

Client / Request

Can include all or none of the resource’s attributes in an update request Can include some or all of a resource’s relationships

Server / Response

Server interprets any missing attributes or relationships as if they were included with their current values (and NOT null or undefined)

• If a relationship is provided, the value will be replaced with the value specified in this member.

Example: Completely replace tags for an article

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "data": {
    "type": "articles",
    "id": "1",
    "relationships": {
      "tags": {
        "data": [
          { "type": "tags", "id": "2" },
          { "type": "tags", "id": "3" }
        ]
      }
    }
  }
}

Destroying a resource

1
2

DELETE /photos/1 HTTP/1.1
Accept: application/vnd.api+json

Doesn’t appear to need the resource id or type in the body of the request.

Working with relationships directly

JSON API treats relationships as their own singular resource, providing APIs for interacting with them directly (regardless of their implementation):

• Each relationship object can contain a link for interacting with the relationship directly
• The behaviour of requests to that URL depend on the HTTP method you use

Viewing Relationships

Returns the relationship object with a data value that is collection or singular resource, depending on whether it’s a to-one or to-many relationship

Updating Relationships

Has the same endpoint shape, regardless of implementation semantics (foreign keys, join tables etc)

Server can choose to delete the underlying resource if a relationship is deleted (as a garbage collection measure).

Update a To-One relationship: Only PATCH is supported - i.e. you’re updating it whether the relation currently exists or not

Client / Request

Client include a top-level member named data containing one of:

• A resource identifier object corresponding to the new related resource.
• null, to remove the relationship.

Swap a relationship

1
2
3
4
5

PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{ "data": { "type": "people", "id": "12" }}

Removing a relationship

1
2
3
4
5

PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{ "data": null}

Update a To-Many relationship: PATCH, POST and DELETE are supported

Client / Request

Body must contain a data member whose value is an empty array or an array of resource identifier objects

POST request: Adding items to a relation

Server / Response

Adds the specified members to the relationship unless they are already present

• If a given type and id is already in the relationship, the server does not add it again

If all of the specified resources can be added to, or are already present in, the relationship then the server returns a successful response.

• Ensures a request is successful if the server’s state matches the requested state
• Helps avoid pointless race conditions caused by multiple clients making the same changes to a relationship.

1

{ "data": [ { "type": "comments", "id": "123" } ]}

PATCH Request: Replaces all existing items in the relation

Server / Response

Either:

• Completely replace every member of the relationship
• Return an appropriate error response if some resources can not be found or accessed
• Return 403 Forbidden

DELETE Request: Remove items from a relation

Server / Response

Removes the specified members from the relationship or return a 403 Forbidden response

If all of the specified resources are able to be removed from, or are already missing from, the relationship then server returns a successful response