Media Type

Return to Web API

Media Type

IASystem uses the Collection+JSON hypermedia type. It defines the format and semantics of the JSON-based representations that are sent and received by the API resources. Although the documents are JSON-encoded, the resources to not accept the JSON media type, application/json. Rather, include the Collection+JSON media type with each request:

Accept: application/vnd.collection+json

Usage and Notes

The Collection+JSON format document is scheduled for some cleanup during March or April of 2015. In the meantime here are clarifications on the type’s semantics and IASystem’s™ implementation:

  • The collection.href property specifies a collection URI within the context of the request URI. It will not specify an item, query, or template URI; nor a rel=”self” URI.
  • The collection.links array will contain a rel=”self” link object with an href property specifying the request URI.
  • The collection.items array need not contain homogeneous objects; in fact, IASystem™ populates it with heterogeneous objects when needed. Collection+JSON does not support nested items; although, there are some extensions that support this. IASystem™ implements a meta-data extension in support of heterogeneous collections.
  • The way item data is structured does not lend itself well to convenient retrieval and setting of a given item’s attributes. A couple common patterns for dealing with this include abstracting the item.data array traversals behind object methods and indexing/hashing the item.data array.
  • The API may return item representations that have no associated API resource. Therefore, these item objects will have no href property.

For more in-depth reading on hypermedia types, the collection pattern, and Collection+JSON see RESTful Web APIs by Richardson & Amundsen and the Collection+JSON google group.

Extensions

Meta-Data

The IASystem™ Web API implements a meta-data extension to Collection-JSON. It does so by adding a meta array property to item objects:

The meta array is a child property of the item objects.

The meta array MAY contain one or more anonymous objects. Each object is composed of two possible properties: name (REQUIRED) and value (REQUIRED).

An item object may be identified by type. It will have a child meta-data object with a name property of “type”.

An item object may have relationships with other item objects. IASystem™ supports child-parent relationships. It will have a child meta-data object with a name property of “id” and zero or more meta-data objects each with a name property of “childId”.

Required Data

The IASystem™ Web API implements a required data extension to Collection-JSON. It does so by adding a property, “required”, to the data objects of the collection.queries array. These data objects represent query parameters. If one must be present for the query to successfully execute it will have a property, “required”, set to the true boolean value.