APIs: Server Side Implementation Notes
Cross-Origin Resource Sharing (CORS)
In order to permit web-based control interfaces to be hosted remotely, all NMOS APIs MUST implement valid CORS HTTP headers in responses to all requests.
In addition to this, where highlighted in the API specifications servers MUST respond to HTTP pre-flight
OPTIONS requests. Servers MAY additionally support HTTP
OPTIONS requests made to any other API resource.
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 possibly not suitable for a production deployment.
Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, PUT, POST, PATCH, HEAD, OPTIONS, DELETE Access-Control-Allow-Headers: Content-Type, Accept Access-Control-Max-Age: 3600
To ensure compatibility, the response
Access-Control-Allow-Headers could be set from the request’s
host attributes are specified in the 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 this specification is intended for use between layer 3 network segments, use of these hostnames can result in Nodes appearing inaccessible.
Uninitialised Senders and Receivers
When a Sender or Receiver is first started it might not have all the parameters it needs to operate. For example IP addresses and port numbers might not be set. In such cases:
- Senders and Receivers SHOULD present sensible default values on transport parameter endpoints. Suggested defaults are given in the relevant schemas. Any default parameters such as port numbers specified in relevant RFCs SHOULD be followed. Parameters where no sensible defaults exist, such as source IP address on a Receiver, SHOULD be set to
- Senders that are not configured (for example have a
nullsource IP address value) SHOULD return
404(Not Found) on their active transport file endpoint, until a usable set of parameters has been activated.
(In other cases, Senders and Receivers might start with parameters already configured, for example through use of a configuration file or manual entry of parameters.)
Use of auto
Many transport parameters MAY be set to
"auto" in the
/staged endpoint, to tell the Sender or Receiver to select the parameter for itself. In many cases this is a simple operation, and the behaviour is very clearly defined in the relevant transport parameter schemas. For example a port number might be offset from the RTP port number by a pre-determined value. The specification makes suggestions of a sensible default value for
"auto" to resolve to, but the Sender or Receiver might choose any value permitted by the schema and constraints.
Transport parameters which need to support
"auto" are defined in the specification. Implementations SHOULD NOT indicate
"auto" as an option via their
In some cases the behaviour is more complex, and can be determined by the vendor. These cases are indicated in section 4 for the specific transport types.
Use of JSON Schema with Constraints
It is strongly RECOMMENDED that API implementations validate requests received from clients against the JSON schema included in this specification. Where additional constraints are applied by the API using the
/constraints resource, these restrictions SHOULD be merged with the provided JSON schema in order to provide consistent validation.
The constraints are used to advertise the available network interfaces on the Device. This happens through use of an
enum constraint, which contains an array of the available interface IP addresses. For interfaces capable of operating with IPv6 and IPv4 each interface SHOULD have two entries containing the interface’s IPv4 and IPv6 addresses. Examples are provided in the API documentation.
Staged Requests Precedence
It is possible to make a
PATCH request to the
/staged Receiver endpoint containing both a transport file and transport parameters. Where the content of the transport file and the transport parameters are not in agreement, the transport parameters take precedence. For example, if a transport file specifies a multicast group address of
18.104.22.168 but the transport parameter
multicast_ip specified a multicast group of
22.214.171.124 then the Receiver will use