Fork me on GitHub

Frequently Asked Questions

Why is JSON API not versioned?

Once JSON API is stable, it will always be backwards compatible using a never remove, only add strategy. #46

Why not use the HAL specification?

There are several reasons:

In short, JSON API is an attempt to formalize similar ad hoc client-server interfaces that use JSON as an interchange format. It is specifically focused around using those APIs with a smart client that knows how to cache documents it has already seen and avoid asking for them again.

It is extracted from a real-world library already used by a number of projects, which has informed both the request/response aspects (absent from HAL) and the interchange format itself.

How to discover resource possible actions?

You should use the OPTIONS HTTP method to discover what can be done with a particular resource. The semantics of the methods returned by OPTIONS is defined by the JSON API standard.

For instance, if "GET,POST" is the response to an OPTIONS request to an URL, then you can get information about the resource and also create new resources.

If you want to know what you can do with a specific resource attribute then you will have to use an application level profile to define the attribute meaning and capabilities and use the errors response to let users know. This error feature is still pending to be included in the standard since is still in discussion.

Where's PUT? Can I use method X to do Y?

JSON API does not currently specify the use of the PUT method for any purpose.

Servers may complement the base specification by providing extra capabilities and alternative ways of requesting certain operations (e.g., resource creation via PUT in addition to POST).

Is there a JSON Schema describing JSON API?

Not currently, no. JSON Schema cannot fully represent the semantics of JSON API, and so any such schema would be partial anyway.

Why are resource collections returned as arrays instead of sets keyed by ID?

A JSON array is naturally ordered while sets require metadata to specify order among members. Therefore, arrays allow for more natural sorting by default or specified criteria.

In addition, JSON API allows read-only resources to be returned without IDs, which would of course be incompatible with a set keyed by IDs.

Why are related resources nested in an included object in a compound document?

Primary resources should be isolated because their order and number is often significant. It's necessary to separate primary and related resources by more than type because it's possible that a primary resource may have related resources of the same type (e.g. the "parents" of a "person"). Nesting related resources in included prevents this possible conflict.