APIs
←Overview · Index↑ · APIs - Common Keys→
This document covers common aspects of the following three APIs:
API Specifications
The Node, Registration and Query APIs are specified using:
- The following sub-sections describing common API properties.
- RAML documents and JSON schemas in the APIs folder.
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 Registration API use these JSON schemas as part of a validation stage when receiving registrations from Nodes. Invalid resources 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 upwards, the response SHOULD include a JSON format array of the child resources available from that point.
API clients using DNS-SD for API discovery SHOULD construct these paths by making use of the TXT records ‘api_proto’ and ‘api_ver’, along with addresses and ports resolved via DNS-SD. API clients which are discovering Node APIs via a Query API SHOULD construct Node API paths using the corresponding data available within the 'api' attributes within the Query API /nodes/ path.
Where protocol and versioning data is not available, clients MAY assume a v1.0 API, which operates via the ‘http’ protocol only.
Versioning
All public APIs are versioned as follows:
- Requesting the API base resource (such as http(s)://<ip address or hostname>:<port>/x-nmos/query/) will provide a list containing the versions of the API present on the node.
- A versioned API response must include only resources which match the schema for that API version.
- Data which is held for mismatched minor API versions may be returned if it can be conformed to the correct schema (see example below). Data must never be conformed between major API versions.
Example
A v1.1 API response may include:
- v1.1 data without modification.
- Data conforming to schemas less than v2.0 but greater than v1.1, with any non-v1.1 keys removed.
- Query API only: Data confirming to schemas less than v1.1 but greater than or equal to v1.0 if a suitable downgrade parameter is specified (see Query Parameters).
Common API Base Resource
[
"v1.0/",
"v2.0/",
"v3.0/"
]
- Appending /v1.0/ to the API base resource will request version 1.0 of the API if available.
- The versioning format is v<#MAJOR>.<#MINOR>
- MINOR increments SHOULD be performed for non-breaking changes (such as the addition of attributes in a response)
- MAJOR increments MUST be performed for breaking changes (such as the renaming of a resource or attribute)
- Versions MUST be represented as complete strings. Parsing MUST proceed as follows: separate into two strings, using the point (.) as a delimiter. Compare integer representations of MAJOR, MINOR version (such that v1.12 is greater than v1.5).
- Clients are responsible for identifying the correct API version they require.
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
- Clients performing requests using these methods SHOULD correctly handle a 301 response (moved permanently).
- When a 301 is supported, the client MUST follow the redirect in order to retrieve the required response payload.
- Servers implementing the APIs MUST support requests using these methods to both the trailing slash and non-trailing slash path to each resource. One of these MAY produce a 301 response causing a redirect to the other if preferred.
All Other Requests (PUT, POST, DELETE, OPTIONS etc)
- Clients performing requests using these methods MUST use URLs with no trailing slash present.
- Servers implementing the APIs MUST correctly interpret requests using these methods to paths without trailing slashes present.
- Servers implementing the APIs MAY correctly interpret requests using these methods to paths with trailing slashes present for backward compatibility.
- Servers SHOULD NOT respond with 3xx codes for these request types.
Client Behaviour
When a server implementation is required to indicate an API URL via an ‘href’ or similar attribute, it is valid to either include a trailing slash or not provided that the listed path is accessible and abides by the policy above. In order to avoid cases of double slashes or missing slashes, clients are required to exercise caution when appending paths onto ‘href’ type attributes.
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.