Building Hypermedia APIs with HTML5 and Node

Appendix E. Collection+JSON Media Type

Collection+JSON is a JSON-based read/write hypermedia type designed to support the management and querying of simple collections. It is similar to the The Atom Syndication Format (RFC 4287) and The Atom Publishing Protocol (RFC 5023) . However, Collection+JSON defines both the format and the semantics in a single document and includes support for Query Templates and expanded write support through the use of a Write Template.

The IANA Registry lists the media type identifier as application/vnd.Collection+JSON.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

General Concepts

This section contains general concepts that apply to all Collection+JSON documents.

The Collection+JSON hypermedia type is designed to support full read/write capability for simple lists (e.g. contacts, tasks, blog entries, etc.). The standard application semantics supported by this media type include Create, Read, Update, and Delete (CRUD) along with support for predefined queries including query templates (similar to HTML GET forms). Write operations are defined using a template object supplied by the server as part of the response representation.

Each item in a Collection+JSON collection has an assigned URI (via the href property) and an optional array of one or more data elements along with an optional array of one or more link elements. ...