json-api/json-api — pull request #237 by dgeb (2014-06-23 02:29:37+00:00)
Title: JSON API v1.0rc1, simplified

*Note: see the [revised format page](https://github.com/dgeb/json-api/blob/v1rc1-simplified/format/index.md) to review the heart of this PR.*

This PR simplifies the original PR #234 by removing two of its most controversial
features:

* Heterogenous (i.e. polymorphic) relationships - This feature adds a lot of
complexity for implementers, since it requires that `type` and `id` must
always be supplied together. This led to awkward URL slugs that merged
`type:id`. Furthermore, based on my personal experience and that of other
implementers, polymorphism in APIs tends to be an anti-pattern that
can almost always be solved more appropriately with a typed solution. I no
longer think that it warrants inclusion in this spec.

* Non-UUID Client IDs - Allowing non-UUID IDs generated on the client to be
passed to the server puts a heavy requirement on server implementers, who
would need to maintain a map of client IDs to newly formed server IDs while
processing requests. My recommendation is to encourage the use of UUIDs, which
can be generated by the client and/or server and use the single `id` field.

My strong preference is to discuss these two features in separate issues during
the RC phase, such that the rest of this PR may be merged sooner than later.

Below is the text of the original PR, modified to reflect the state of this PR.

------------------

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.

* 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 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.