From 452de048d4c735695a4f4f86d097349f98ea8c43 Mon Sep 17 00:00:00 2001 From: Gareth Sylvester-Bradley <31761158+garethsb@users.noreply.github.com> Date: Wed, 12 May 2021 22:08:59 +0100 Subject: [PATCH] Update 3.1 Interop - IS-04 (#134) * Add more detail on the equivalence between Connection API /active parameters and Node API subscription attributes * Not "NMOS IS-04" --- ...MOS IS-04.md => 3.1. Interoperability - IS-04.md} | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) rename docs/{3.1. Interoperability - NMOS IS-04.md => 3.1. Interoperability - IS-04.md} (68%) diff --git a/docs/3.1. Interoperability - NMOS IS-04.md b/docs/3.1. Interoperability - IS-04.md similarity index 68% rename from docs/3.1. Interoperability - NMOS IS-04.md rename to docs/3.1. Interoperability - IS-04.md index d0f5207..12312a9 100644 --- a/docs/3.1. Interoperability - NMOS IS-04.md +++ b/docs/3.1. Interoperability - IS-04.md @@ -1,8 +1,8 @@ -# Interoperability: NMOS IS-04 +# Interoperability: IS-04 _(c) AMWA 2017, CC Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)_ -The Connection API shares a data model with the NMOS IS-04 specification, and as a result it is designed to be used alongside it. The following implementation notes identify correct behaviour for doing this. +The Connection API shares a data model with the IS-04 specification, and as a result it is designed to be used alongside it. The following sub-sections identify correct behaviour for doing this. When this API is used alongside IS-04 in a deployment, the IS-04 APIs SHOULD be operating at version 1.2 or greater in order to ensure full interoperability. @@ -39,7 +39,7 @@ The UUIDs used to advertise Senders and Receivers in the Connection API MUST mat ## Version Increments -In order to prevent unnecessary polling of the Connection API, changes to active connection parameters are signalled via the IS-04 versioning mechanism. When the `active` parameters of a Sender or Receiver are modified, or when a re-activation of the same parameters is performed, the `version` attribute of the relevant IS-04 Sender or Receiver MUST be incremented. +In order to prevent unnecessary polling of the Connection API, changes to active connection parameters are signalled via the IS-04 versioning mechanism. When the active parameters of a Sender or Receiver are modified, or when a re-activation of the same parameters is performed, the `version` attribute of the relevant IS-04 Sender or Receiver MUST be incremented. ## Identifying Active Connections @@ -49,8 +49,8 @@ In order to populate the `subscription` attribute of IS-04 Senders and Receivers The Connection API supersedes the now deprecated method of updating the `/target` resource on Node API Receivers in order to establish connections. The two methods of operation are likely to co-exist until Version 2.0 of IS-04. As such the following best practice SHOULD be followed when both are in use: -- Where a client updates the Node API subscription, the result on the Connection API SHOULD be the same as if the client had first staged the parameters and then called an immediate activation. That is to say that the new parameters will be reflected both in the staged and active endpoints of the Receiver. -- Where a client updates a Connection API Receiver the active `sender_id` parameter SHOULD be populated in the Node API subscription parameter with key `sender_id`. -- After a Connection API activation the corresponding Sender or Receiver's `version` property SHOULD be updated to the instant of the activation. +- Where a client establishes a connection via the Node API `/target` resource, which updates the Receiver's `subscription` object, the result on the Connection API SHOULD be as if the client had staged the parameters and requested an immediate activation to enable the Receiver. That is to say that the new parameters, including the `sender_id` and with `master_enable` set to `true`, will be reflected in both the `/staged` and `/active` endpoints of the Receiver. +- When the active parameters of a Sender or Receiver are modified via a Connection API activation, the Node API Sender or Receiver `subscription` object SHOULD be updated to reflect the active state. That is to say that the `active` attribute and the `receiver_id` or `sender_id` of the `subscription` object will match the `master_enable` and `receiver_id` or `sender_id` values in the Connection API `/active` endpoint. +- The `version` attribute of the Node API resource is also updated on every activation, as described in [Version Increments](#Version-Increments). If staged modifications are present when a legacy activation is performed, these parameters MUST be discarded in favour of those provided via the Node API interface.