# APIs: Server Side Implementation Notes

_(c) AMWA 2017, CC Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)_

## 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.

```http
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`.
