account-rest-api v1.1.0

account-rest-api

RESTful JSON API-blueprint for all things user accounts

This is a JSON API v1.0 compliant implementation.

JSON API

Some key information from the spec;

Content Negotiation

Client Responsibilities

Clients MUST send all JSON API data in request documents with the header Content-Type: application/vnd.api+json without any media type parameters.

Clients that include the JSON API media type in their Accept header MUST specify the media type there at least once without any media type parameters.

Clients MUST ignore any parameters for the application/vnd.api+json media type received in the Content-Type header of response documents.

Server Responsibilities

Servers MUST send all JSON API data in response documents with the header Content-Type: application/vnd.api+json without any media type parameters.

Servers MUST respond with a 415 Unsupported Media Type status code if a request specifies the header Content-Type: application/vnd.api+json with any media type parameters.

Servers MUST respond with a 406 Not Acceptable status code if a request's Accept header contains the JSON API media type and all instances of that media type are modified with media type parameters.

Document Structure

Top Level

A JSON object MUST be at the root of every JSON API request and response containing data. This object defines a document's "top level".

A document MUST contain at least one of the following top-level members:

• data: the document's "primary data"
• errors: an array of error objects
• meta: a meta object that contains non-standard meta-information.

The members data and errors MUST NOT coexist in the same document.

A document MAY contain any of these top-level members:

• jsonapi: an object describing the server's implementation
• links: a links object related to the primary data.
• included: an array of resource objects that are related to the primary data and/or each other ("included resources").

If a document does not contain a top-level data key, the included member MUST NOT be present either.

And from the FAQ;

Where's PUT?

Using PUT to partially update a resource (i.e. to change only some of its state) is not allowed by the HTTP specification. Instead, PUT is supposed to completely replace the state of a resource:

“The PUT method requests that the state of the target resource be created or replaced with the state…in the request message payload. A successful PUT of a given representation would suggest that a subsequent GET on that same target resource will result in an equivalent representation being sent…”

The correct method for partial updates, therefore, is PATCH, which is what JSON API uses. And because PATCH can also be used compliantly for full resource replacement, JSON API hasn't needed to define any behavior for PUT so far. However, it may define PUT semantics in the future.

In the past, many APIs used PUT for partial updates because PATCH wasn’t yet well-supported. However, almost all clients now support PATCH, and those that don’t can be easily worked around.

See documentation on http://docs.accountrestapi.apiary.io/

Send your suggestion to the apiary.apib file

License

MIT