JSON API Isn't Good or Bad

 JSON API
 Specification
 Extensions
 Recommendations
 Examples
 Implementations
 FAQ
 About
 V1.0 STABLE
A SPECIFICATION FOR BUILDING APIS IN JSON
View the specification Contribute on GitHub

If you’ve ever argued with your team about the way your JSON responses should be
formatted, JSON:API can be your anti-bikeshedding tool.
By following shared conventions, you can increase productivity, take advantage of

generalized tooling, and focus on what matters: your application.
Clients built around JSON:API are able to take advantage of its features around
efficiently caching responses, sometimes eliminating network requests entirely.
Here’s an example response from a blog that implements JSON:API:
"links": {
"self": "http://example.com/articles",
"next": "http://example.com/articles?page[offset]=2",
"last": "http://example.com/articles?page[offset]=10"
},
"data": [{
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON:API paints my bikeshed!"
},
"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" }
},
"links": {
"self": "http://example.com/articles/1"
}],
"included": [{
"type": "people",
"id": "9",
"attributes": {
"firstName": "Dan",
"lastName": "Gebhardt",
"twitter": "dgeb"
},
"links": {
"self": "http://example.com/people/9"
}
}, {
"type": "comments",
"id": "5",
"attributes": {
"body": "First!"
},
"relationships": {
"author": {
},
"links": {
"self": "http://example.com/comments/5"
}, {
"type": "comments",
"id": "12",
"attributes": {
"body": "I like XML better"

},
"relationships": {
"author": {
},
"links": {
"self": "http://example.com/comments/12"
}]
The response above contains the first in a collection of “articles”, as well as links to
subsequent members in that collection. It also contains resources linked to the article,
including its author and comments. Last but not least, links are provided that can be
used to fetch or update any of these resources.
JSON:API covers creating and updating resources as well, not just responses.
MIME Types
JSON:API has been properly registered with the IANA. Its media type designation
is application/vnd.api+json.
Format documentation
To get started with JSON:API, check out documentation for the base specification.
Extensions
The JSON:API community has created a collection of extensions that APIs can use to
provide clients with information or functionality beyond that described in the base
JSON:API specification. These extensions are called profiles.
You can browse existing profiles or create a new one.
Update history
 2020-10-01: 1.1 Release candidate 3 released.
o Refined links objects. The link object params member was removed to
better align with other JSON link serializations. The anchor target
attribute was also removed. It may be restored in a future minor release.
o Extensions were added and the scope of profiles were reduced since their
introduction in RC1.
o Links can be represented as RFC 8288-style web links.
o A new describedby links member was added so that implementors can
incorporate description documents (e.g. OpenAPI or JSON Schema)
directly into their APIs.
o Local IDs were introduced so that a client can create a relationship to a
resource yet-to-be created by the same request.
o New features include: profiles, ”@-Members”, and error object type links.
o There are editorial clarifications around: query parameters (their
parsing/serialization, and reserved parameter names), the appropriate
status code for specific responses, and the presence of
the included key even when its value is an empty array.
o JSON:API switched to recommending camelCased names.
 2015-05-29: 1.0 final released.
 2013-07-21: Media type registration completed with the IANA.
 2013-05-03: Initial release of the draft.
You can subscribe to an RSS feed of individual changes here.
Built with Jekyll and Highlight.js

JSON API Isn't Good or Bad

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

JSON API Isn't Good or Bad

Uploaded by

Copyright:

Available Formats

 JSON API

A SPECIFICATION FOR BUILDING APIS IN JSON

View the specification Contribute on GitHub

By following shared conventions, you can increase productivity, take advantage of

Here’s an example response from a blog that implements JSON:API:

"title": "JSON:API paints my bikeshed!"

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

{ "type": "comments", "id": "5" },

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

"body": "I like XML better"

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

You can browse existing profiles or create a new one.

You can subscribe to an RSS feed of individual changes here.

Built with Jekyll and Highlight.js

You might also like