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 may not be 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 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. These cases are indicated in section 4 against 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 is done through use of an enum constraint, which contains an array of the available interface IP addresses, and the “auto” option. 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 raml 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 should use 232.20.44.7.