APIs: Client Side Implementation Notes
←APIs · Index↑ · APIs - Server Side Implementation→
Conforming to Schemas
When interacting with a Connection Management API, a client may assume the presence of a core set of attributes for each defined transport type. Other parameters may be defined by the specification, but are optional for implementations given that they may or may not implement a particular feature. Presence of these attributes in an implementation cannot be assumed and must be identified via the ‘/constraints’ resource of a running Device. A list of core attributes, and attributes associated with particular features, is given in 4.1 Behaviour - RTP Transport Type.
For core attributes, individual APIs may still constrain their permitted values to a particular range or enumeration, so parsing the constraints is still recommended.
RTP Operating Point
When establishing an RTP connection between two Devices that implement NMOS Connection Management, the expectation is that the primary means of connection will be to supply the SDP file from the Sender to the Receiver. This ensures Receivers have the media information in the SDP file. If desired the client may adjust individual transport parameters on the Receiver. For example it may use the rtcp_enable parameter to toggle RTCP operation.
When receiving from a (non-NMOS) Device which does not provide an SDP file, a connection may be established using transport parameters alone. In this case it may be necessary to provide media information out-of-band.
Failure Modes
If a client receives an HTTP 500 response code from the API a failure has occurred. The client should display the content of the response’s error field to the user if possible, and indicate that the Device may be in a bad state. The client should also refresh the values in the /staged and /active endpoints to ensure it is accurately reflecting the current state of the API.
If an activation is triggered across multiple Senders and Receivers using the /bulk interface, Senders and Receivers will transition to their new active parameters, even if some Senders or Receivers in the same salvo fail to activate. It is the responsibility of the client to recover from this situation if desired, including reverting Senders and Receivers that have successfully activated back to their original state where necessary.