This page contains additional examples of how to apply various parts of the specification.

Sparse Fieldsets

Examples of howsparse fieldsets work.

Basic request:

GET/articles?include=authorHTTP/1.1

HTTP/1.1200OKContent-Type:application/vnd.api+json{"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"}}]}

Request withfields[articles] andfields[people] parameters:

GET/articles?include=author&fields[articles]=title,body,author&fields[people]=nameHTTP/1.1

Note: The above example URI shows unencoded[ and] characters simplyfor readability. In practice, these characters should be percent-encoded, asnoted in the base specification. See “Square Brackets in Parameter Names”.

Here we wantarticles objects to have fieldstitle,body andauthor only andpeople objects to havename field only.

HTTP/1.1200OKContent-Type:application/vnd.api+json{"data":[{"type":"articles","id":"1","attributes":{"title":"JSON:API paints my bikeshed!","body":"The shortest article. Ever."},"relationships":{"author":{"data":{"id":"42","type":"people"}}}}],"included":[{"type":"people","id":"42","attributes":{"name":"John"}}]}

Pay attention to the fact that you have to add a relationship name both ininclude andfields (since relationships are fields too), otherwise you’ll get:

GET/articles?include=author&fields[articles]=title,body&fields[people]=nameHTTP/1.1

HTTP/1.1200OKContent-Type:application/vnd.api+json{"data":[{"type":"articles","id":"1","attributes":{"title":"JSON:API paints my bikeshed!","body":"The shortest article. Ever."}}],"included":[{"type":"people","id":"42","attributes":{"name":"John"}}]}

Note: The above example URI shows unencoded[ and] characters simplyfor readability. In practice, these characters should be percent-encoded, asnoted in the base specification. See “Square Brackets in Parameter Names”.

Pagination Links

Example of a page-based strategy on how to addpagination links.

Basic request:

GET/articles?page[number]=3&page[size]=1HTTP/1.1

HTTP/1.1200OKContent-Type:application/vnd.api+json{"meta":{"totalPages":13},"data":[{"type":"articles","id":"3","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"}}],"links":{"self":"http://example.com/articles?page[number]=3&page[size]=1","first":"http://example.com/articles?page[number]=1&page[size]=1","prev":"http://example.com/articles?page[number]=2&page[size]=1","next":"http://example.com/articles?page[number]=4&page[size]=1","last":"http://example.com/articles?page[number]=13&page[size]=1"}}

Note: The above example URIs show unencoded[ and] characters simplyfor readability. In practice, these characters should be percent-encoded, asnoted in the base specification. See “Square Brackets in Parameter Names”.

Note: Putting a property like"totalPages" in"meta" can be a convenient wayto indicate to clients the total number of pages in a collection (as opposed tothe"last" link, which simply gives the URI of the last page). However, all"meta" values are implementation-specific, so you can call this member whateveryou like ("total","count", etc.) or not use it at all.

Error Objects

Examples of howerror objects work.

A Basic Error Object

In the response below, the server is indicating that it encountered an errorwhile creating/updating the resource, and that this error was causedby an invalid"firstName" attribute:

HTTP/1.1422Unprocessable EntityContent-Type:application/vnd.api+json{"errors":[{"status":"422","source":{"pointer":"/data/attributes/firstName"},"title":"Invalid Attribute","detail":"First name must contain at least two characters."}]}

Every member in an error object is optional, but all help the clientby providing extra details.

Thesource member is used toindicatewhich part of the request document caused the error.

Thetitle anddetail members are similar, butdetail is specificto this occurrence of the problem, whereastitle is more generic.

Thestatus member represents the HTTP status code associated with the problem.It’s very helpful when multiple errors are returned at once (see below), as theHTTP response itself can only have one status code. However, it can also beuseful for single errors, to save clients the trouble of consulting the HTTPheaders, or for using JSON:API over non-HTTP protocols, which may be officiallysupported in the near future.

Multiple Errors

When multiple errors occur in response to a single request, the servercan simply add each error to theerrors array:

HTTP/1.1400Bad RequestContent-Type:application/vnd.api+json{"errors":[{"status":"403","source":{"pointer":"/data/attributes/secretPowers"},"detail":"Editing secret powers is not authorized on Sundays."},{"status":"422","source":{"pointer":"/data/attributes/volume"},"detail":"Volume does not, in fact, go to 11."},{"status":"500","source":{"pointer":"/data/attributes/reputation"},"title":"The backend responded with an error","detail":"Reputation service not responding after three requests."}]}

The only uniqueness constraint on error objects is theid field. Thus,multiple errors on the same attribute can each be given their own errorobject. The example below shows multiple errors on the"firstName" attribute:

HTTP/1.1422Unprocessable EntityContent-Type:application/vnd.api+json{"errors":[{"source":{"pointer":"/data/attributes/firstName"},"title":"Invalid Attribute","detail":"First name must contain at least two characters."},{"source":{"pointer":"/data/attributes/firstName"},"title":"Invalid Attribute","detail":"First name must contain an emoji."}]}

Note: in the responses above with a 422 status code,400 Bad Request wouldalso be acceptable. (More details.)JSON:API doesn’t take a position on 400 vs. 422.

Error Codes

Thecode member of an error object contains an application-specific coderepresenting the type of problem encountered.code is similar totitlein that both identify a general type of problem (unlikedetail, which isspecific to the particular instance of the problem), but dealing withcodeis easier programmatically, because the “same”title may appear in differentforms due to localization.

For the example below, imagine the API docs specified the following mapping:

Multiple errors on"password" attribute, with errorcode:

HTTP/1.1422Unprocessable EntityContent-Type:application/vnd.api+json{"jsonapi":{"version":"1.1"},"errors":[{"code":"123","source":{"pointer":"/data/attributes/firstName"},"title":"Value is too short","detail":"First name must contain at least two characters."},{"code":"225","source":{"pointer":"/data/attributes/password"},"title":"Passwords must contain a letter, number, and punctuation character.","detail":"The password provided is missing a punctuation character."},{"code":"226","source":{"pointer":"/data/attributes/password"},"title":"Password and password confirmation do not match."}]}

Notice that this response includes not only theerrors top-level member,but thejsonapi top-level member. Error responses cannot contain thetop-leveldata member, but can include all the other top-level membersJSON:API defines.

Also, notice that the third error object lacks adetail member (perhapsfor security). Again, all error object members are optional.

Advancedsource Usage

In the example below, the user is sending an invalid JSON:APIrequest, because it’s missing thedata member:

PATCH/posts/1HTTP/1.1Content-Type:application/vnd.api+jsonAccept:application/vnd.api+json{"datum":[]}

Therefore, the server responds:

HTTP/1.1422Unprocesssable EntityContent-Type:application/vnd.api+json{"errors":[{"source":{"pointer":""},"detail":"Missing `data` Member at document's top level."}]}

It usessource to point to the top-level of the document ("").(Pointing to “/” would be an appropriate reference to the string"some value" in the request document{"": "some value"}.Pointing to"/data" would be invalid because the request document didnot have a value at"/data", andsource is always given with referenceto the request document.)

If the server cannot parse the request as valid JSON, includingsource doesn’t make sense (because there’s no JSON document forsource torefer to). Here’s how the server might respond to an invalid JSON document:

{"errors":[{"status":"400","detail":"JSON parse error - Expecting property name at line 1 column 2 (char 1)."}]}

Invalid Query Parameters

Thesource member can also be used to indicate that the error originatedfrom a problem with a URI query parameter, like so:

GET/api/posts/1?include=authorHTTP/1.1

HTTP/1.1400Bad RequestContent-Type:application/vnd.api+json{"errors":[{"source":{"parameter":"include"},"title":"Invalid Query Parameter","detail":"The resource does not have an `author` relationship path."}]}

In most cases, JSON:API requires the server to return an error when it encountersan invalid value for a JSON:API–defined query parameter. However, for API-specificquery parameters (i.e. those not defined by JSON:API), a server may choose toignore an invalid parameter and have the request succeed, rather than respond withan error.API-specific query parameters must contain one non a-zcharacter.

Other examples of invalid parameters include:?fields[people]= (invalid parameter name;should befields[people]) and?redirect_to=http%3A%2F%2Fwww.owasp.org (invalid parameter,in this case, a phishing attack), etc.