APIs: Server Side Implementation Notes

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

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

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 may result in Nodes appearing inaccessible.

Un-initialised Senders and Receivers

When a Sender or Receiver is first started it may not have all the parameters it needs to operate. For example IP addresses and port numbers may not be set. In this instance:

Senders and Receivers should present sensible default values on transport parameter endpoints. Suggested defaults are given in the relevant schemas. Parameters such as port numbers may have defaults in various RFCs that 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 on their active transport file endpoint, until a usable set of parameters has been activated.

However Senders and Receivers may start with parameters already configured, for example through use of a configuration file or manual entry of parameters.

Use of auto

Many transport parameters in the API may be set to “auto” in the /staged endpoint, to imply the Sender or Receiver should select that 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 may 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 may choose any value permitted by the schema and constraints.

Transport parameters which are required to support “auto” are defined in the specification. It is not recommended for implementations to indicate “auto” as an option via their /constraints endpoint.

In some cases the behaviour is more complex, and may be determined by the vendor. The following sub-sections provide guidance on these more complex cases.

Sender `source_ip` and Receiver `interface_ip`

These parameters specify the interface binding to use for sending or receiving RTP traffic. Use of auto here implies the Device should determine for itself which of its interfaces is the most appropriate to use. In Devices where only one interface is available for media traffic this is trivial. In Devices with multiple media network interfaces Devices may use mechanisms such as routing tables, out-of-band controls or evaluation of loading on the interfaces.

Sender `destination_ip`

If this parameter is set to auto the Sender is expected to automatically select a multicast address to send on. This may be determined by an external network control system, or through technologies such as MADCAP (RFC 2730) or ZMAAP.

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 may be done 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.

Behaviour of Media Information

SDP files contain both connection information and media information. When a parameter set is activated with an SDP file present in data the Receiver should use the media information in the SDP file.

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 should use 232.20.44.7.