Generic API Server

Trailing Slashes

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

In order to overcome shortcomings in some common libraries, requirements are imposed for the support of URL paths with or without trailing slashes. For the latest information on these requirements please refer to the API specifications.

Cross-Origin Resource Sharing (CORS)

In order to permit web control interfaces to be hosted remotely, all NMOS APIs must implement valid CORS HTTP headers in responses, and respond to HTTP pre-flight OPTIONS requests. In order to simplify development, the following headers may be returned in order to remove these restrictions as far as possible. Note that these are very relaxed and may not be suitable for a production deployment.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, PUT, POST, HEAD, OPTIONS, DELETE
Access-Control-Allow-Headers: Content-Type, Accept
Access-Control-Max-Age: 3600

At a minimum, an 'Access-Control-Allow-Origin' header must be returned in the response to any type of HTTP request, including GET and HEAD.

To ensure compatibility, the response 'Access-Control-Allow-Headers' could be set from the request's 'Access-Control-Request-Headers'.

Use of '.local' Hostnames

Where attributes such as 'href' or 'host' are specified in APIs, it is strongly recommended to use either IP addresses or hostnames which are resolvable using unicast DNS. Whilst '.local' hostnames are convenient in a zero-configuration layer 2 network segment, these are not usually resolvable beyond these boundaries. As the NMOS specifications are intended for use between layer 3 network segments, use of these hostnames may result in systems appearing inaccessible.

Error Responses

The NMOS APIs use HTTP status codes to indicate success, failure and other cases to clients as per RFC 7231 and related standards. In addition, to provide the best developer experience, servers are required to return details of errors via response bodies. Please see the API documentation for the latest requirements.