Networked Media Open Specifications

APIs

←Overview · Index↑ · APIs - Client Side Implementation→

API Specifications

The Channel Mapping API is specified using:

Examples of JSON format output are provided in the examples folder.

API Validation

JSON schemas are included with the RAML API definitions. These include validation for values used within the APIs. It is strongly recommended that implementers of a Channel Mapping API use these JSON schemas as part of a validation stage when receiving interactions from clients. Invalid payloads should cause a 400 HTTP error (Bad Request) to be returned to the client.

Content Types

All APIs MUST provide a JSON representation signalled via ‘Content-Type: application/json’ headers. This SHOULD be the default content type in the absence of any requested alternative by clients. Other content types (such as HTML) are permitted if they are explicitly requested via Accept headers.

API Paths

All NMOS APIs MUST use a path in the following format. Other HTTP resources MAY be presented on the same port by the Node, provided all NMOS resources are available from the /x-nmos/ path as follows:

http(s)://<ip address or hostname>:<port>/x-nmos/<api type>/<api version>/

At each level of the API from the base resource onwards, the response SHOULD include a JSON format array of the child resources available from that point.

Nodes MAY extend the path for the Channel Mapping API with a suffix. For example, a Node implementation might choose to extend the path so that Devices on the Node have separate Channel Mapping API instances without having to use a different port for each Device’s API. Such a path MUST be formatted as follows:

http(s)://<ip address or hostname>:<port>/x-nmos/<api type>/<api version>/<api selector>/

The <api selector> identifier MUST conform to the following regex pattern:

^[a-zA-Z0-9\-_]+$

This permits the use of a UUID, such as an associated IS-04 Device id, in the usual format or succinct local identifiers such as slot2B.

Versioning

All public APIs are versioned as follows:

Versioning Example

A v1.1 API response may include:

Common API Base Resource

[
  "v1.0/",
  "v2.0/",
  "v3.0/"
]

URLs: Approach to Trailing Slashes

For consistency and in order to adhere to how these APIs are specified in RAML, the ‘primary’ path for every resource has the trailing slash omitted.

In order to overcome shortcomings in some common libraries, the following requirements are imposed for the support of URL paths with or without trailing slashes.

GET and HEAD Requests

All Other Requests (PUT, POST, DELETE, OPTIONS etc)

Error Codes & Responses

The NMOS APIs use HTTP status codes to indicate success, failure and other cases to clients as per RFC 7231 and related standards. Where the RAML specification of an API specifies explicit response codes it is expected that a client will handle these cases in a particular way. As explicit handling of every possible HTTP response code is not expected, clients must instead implement more generic handling for ranges of response codes (1xx, 2xx, 3xx, 4xx and 5xx). For HTTP codes 400 and upwards, a JSON format response MUST be returned as follows:

Example Error Response

{
  "code": 400,
  "error": "Human readable message which is suitable for user interface display, and helpful to the user",
  "debug": "Programmer / debugging detail or traceback"
}

In the above example, the ‘code’ should always match the HTTP status code. ‘error’ must always be present and in string format. ‘debug’ may be null if no further debug information is available.

Further details on when APIs will respond with particular codes is covered in the Behaviour section.

←Overview · Index↑ · APIs - Client Side Implementation→