Provide more specific media type

[joostfarla]

The documentation provides a clear description of how responses are structured:

A OCS response MUST consist of the following elements:

ocs: Array that contains the whole response meta: Array that contains meta information status: The status of the response, either “ok” or “fail”. MUST be “ok” if statuscode is set to 200, “fail” otherwise. statuscode: The OCS status code of the response. 200 indicates a successful response. message: An optional message that MAY contain a status message, such as a error message. data: Array that contains the actual response, content of the array depends completely on the endpoint.

Describing the global response format is where media types are meant for. Media types are part of the contract between server and client and provide instructions on how the data should be handled, e.g. its format or the way certain information is embodied or embedded.

There are lots of existing media types, which provides similar structures:

http://stateless.co/hal_specification.html (application/hal+json / application/hal+xml) http://jsonapi.org/format/ (application/vnd.api+json)

If no standard media type suffices, you could provide a custom media type, for example:

application/vnd.ocm.v1+json
application/vnd.ocm.v1+xml

This gives providers some extra advantages:

• You can serve your own preferred media type, next to the OCM media type (using content negotiation). This makes the provider less dependent on OCM.
• OCM can change representations across media type versions without affecting provider's API versions.
• The media type can describe hypermedia controls (also called HATEOAS, which we will describe in a separate issue).

Custom media types could inherit from a more generic media type, like HAL. You can even register your vendor media type at IANA, the central registry for media types.

[michielbdejong]

This is a discussion around a practice from long ago and has since been resolved. Closing.