json-api/json-api — pull request #234 by dgeb (2014-06-09 16:11:59+00:00)
Title: Refactoring in preparation for JSON API v1.0rc1

This is a fairly thorough rewrite of the spec that formalizes its structure and addresses many outstanding issues.

The goal of this rewrite is to prepare JSON API for 1.0 versioning with a release candidate phase. We would like to shake out any breaking changes during this RC phase to provide implementers the degree of confidence they deserve from this spec.

Any and all feedback is welcome, either in this PR or in the specific issues that it addresses.

Changes include:

* New introduction explains the basics requirements and goals of JSON API. It
also broadly explains the new optional PATCH support and how "JSON API
represents all of a domain's resources as a single JSON document that can act
as the target for operations".

* New "Conventions" section explains SHOULD, MUST, etc. keywords

* New "Document Structure" section describes the JSON API media type
(application/vnd.api+json). This media type is used for both request and
response documents (except for PATCH requests/responses).

* Introduces the option to key the primary resource by the generic `data` key.
This key SHOULD be used for variable type (i.e. heterogenous) resource
collections and MAY be used for constant type (i.e. homogenous) resource
collections.

* Clarify different representations allowed for singular and plural resources.

* BREAKING CHANGE: Singular resource objects SHOULD now be be represented with
JSON objects instead of arrays. This allows for symmetrical representations in
request and response documents, as well as PUT/POST requests and PATCH
operations. It also simplifies implementations which do not support batch
operations (i.e. they can allow an object and not an array).

* Define URLs for resources, collections of resources and resource
relationships. Allow for alternative URL definitions to be specified in
responses.

* BREAKING CHANGE: Allow the baseline implementation of JSON API to operate via
POST, PUT and DELETE alone (no PATCH required). This introduces brand new
specs for updating resources via PUT and updating relationships via POST and
DELETE requests to newly specified relationship URLs. It also specifies how
resources can be created, updated and deleted in bulk (but only per type).

* Introduce alternative JSON PATCH syntax for all operations. This builds off
the current spec's approach to updating relationships. JSON PATCH bulk
operations are discussed.

* Introduce a "Filtering" section in "Fetching". Since we encourage keeping all
resources accessible at the root level, it corresponds that root level
filtering should be encouraged instead of filtering via nested routes.
Furthermore, root level filtering is more flexible because it allows for more
than one filter to be applied to a collection.

* Introduce a `clientid` key that can be used to correlate a resource on the
client with a newly created resource on the server.

* Introduce error objects, which are specialized resource objects that MAY be
returned in a response to provide additional information about problems
encountered while performing an operation.