About

Channels

JSON:API is:

• @jsonapi on Twitter
• #jsonapi channel on Freenode IRC
• jsonapi discussion forum

Editors

There are four active editors of this specification:

• Yehuda Katz
• Dan Gebhardt
• Gabe Sullice
• Jeldrik Hanschke

The following emeritus editors are no longer active:

• Tyler Kellen
• Steve Klabnik
• Ethan Resnick

History

JSON:API was originally drafted by Yehuda Katz in May 2013. This first draft was extracted from the JSON transport implicitly defined by Ember Data’s REST adapter.

In general, Ember Data’s goal is to eliminate the need for ad-hoc code per application to communicate with servers that communicate in a well-defined way.

Some servers, like Firebase, Parse and CouchDB already define strict communication protocols for clients, and were good fits for Ember Data. In contrast, servers written in Rails, Node, and Django tend to be written in a “REST-style” but lack the precision necessary for drop-in client code.

The REST Adapter in Ember Data implicitly defined a protocol that custom servers could implement to get a drop-in client for all of their resources. ActiveModel::Serializers is a proof-of-concept library for Rails that implemented the serialization format expected by Ember Data.

Record creation, update, and deletion was defined implicitly by the Ember Data library and was close to conventions already in wide use by Rails, Django and Node developers.

The goals of the media type are to balance:

• A generic media type that can work across a broad set of use cases, including the generally used relationship types
• Similarity to existing server-side framework practices (and human readability for debugging)
• Ease of implementation on the server side
• Ease of implementation on the client side

This specification reached a stable version 1.0 on May 29, 2015.

Update history

• 2022-09-30: 1.1 final released.
• 2022-08-22: 1.1 Release candidate 4 released.
  • Formalized the definition of specification and implementation semantics.
  • Refined the definitions of extensions and profiles.
  • Clarified details regarding expected and allowed responses, query parameters, and more.
• 2020-10-01: 1.1 Release candidate 3 released.
  • 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.
• 2020-08-20: 1.1 Release candidate 2 released.
  • Extensions were added and the scope of profiles were reduced since their introduction in RC1.
  • Links can be represented as RFC 8288-style web links.
  • A new describedby links member was added so that implementors can incorporate description documents (e.g. OpenAPI or JSON Schema) directly into their APIs.
  • Local IDs were introduced so that a client can create a relationship to a resource yet-to-be created by the same request.
• 2018-12-01: 1.1 Release candidate 1 released.
  • New features include: profiles, ”@-Members”, and error object type links.
  • 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.
  • JSON:API switched to recommending camelCased names.
• 2015-05-29: 1.0 final released.
• 2015-05-21: 1.0 Release candidate 4 released.
• 2015-03-16: 1.0 Release candidate 3 released.
• 2015-02-18: 1.0 Release candidate 2 released.
• 2014-07-05: 1.0 Release candidate 1 released.
• 2013-07-21: Media type registration completed with the IANA.
• 2013-05-03: Initial release of the draft.