API path with <device selector>

[garethsb]

https://github.com/AMWA-TV/nmos-audio-channel-mapping/blob/v1.0.x/docs/2.0.%20APIs.md#api-paths, unusually for NMOS specs, permits the API path to include an optional component to allow the same host/port to host multiple instances of the API. Besides being inconsistent with other NMOS APIs, there doesn't seem to be a spec/pattern for the <device selector> component?

[peterbrightwell]

I agree -- this means that 2.0. APIs.md is inconsistent with the other specs, making it more difficult to refactor things. Ideally this document would be in the proposed nmos-core, with individual specs making additions only as required. From discussions here in Basingstoke it does look like a real requirement and the test suite now supports it.

Some questions:

• Given a Devices does have a UUID, is there a reason not to use it as the selector? That would help with Gareth's second point.
• Might this pattern appear elsewhere? [Gareth has mentioned a possible case where it might]
• Would the version depend on the device selector?

[garethsb]

After discussion with Chris G, Pete B and Andrew B, we suggest adding a sentence before the last one of APIs - API Paths:

The <device selector> identifier MUST conform to the following regex pattern:

^[a-zA-Z0-9\-_]+$

This regex is familiar from the constraints on the IS-08 API URL parameters {inputId} and {outputId}. Those are defined in Behaviours - Inputs and Outputs - Identifiers, though (in common with other URL parameters in NMOS specs) the constraint is not explicit in the RAML.

The regex allows 'device selectors' like slot2B used in Example 2 of Interoperability - NMOS IS-04 - Discovery. Equally a UUID, such as the IS-04 Device id itself, would also be valid.

It prohibits a device selector like foo/bar/baz or even ../../../meow/purr/hiss as well as 👎.

For inputs, outputs and the device selector, the intent of the constraint is to provide succinct* machine-readable identifiers, but given their implicit scope to the API instance, not require UUIDs. In all cases, there are other ways to provide human-readable information, the IS-04 Device label and description or the IS-08 Input/Output /properties resources which include name and description.

*Since there's no length limit, however, brevity is left to the implementer currently...