APIs: Server Side Implementation Notes

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

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 Access-Control-Request-Headers.

Use of `.local` Hostnames

Where href or 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 null.
Senders that are not configured (for example have a null source 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 /constraints endpoint.

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.

Constraints

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.

Constraining Interfaces

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 232.19.133.29 but the transport parameter multicast_ip specified a multicast group of 232.20.44.7 then the Receiver will use 232.20.44.7.