search

AMWA-TV / is-13

AMWA IS-13 NMOS Annotation Specification [Work In Progress]
https://specs.amwa.tv/is-13
Apache License 2.0
1 stars 1 forks source link

Restrict use of API to certain resources? #9

Closed peterbrightwell closed 1 year ago

peterbrightwell commented 1 year ago

Discussion 2023-05-04 assumption was that we only use this API on nodes, devices, senders and receivers, whereas sources and flows might be more dynamic so this API is less useful for them.

Note that senders and receivers could also be dynamic and it also needs to be allowed for those not to be user-labelled (but they will have factory labels)

Should the above be formalised in the specification?

garethsb commented 1 year ago

whereas sources and flows might be more dynamic so this API is less useful for them.

Could well be the case, but I recommend leaving this to usage. I don't see the benefit in prohibiting this in the spec.

Since API implementations can reject PATCH requests with 500 errors per their own limitations, it could be reasonable for some highly dynamic implementations to only support updates to Node, Device, Sender and Receiver resources, while others may support updates on all resources?

Or dynamic implementations could only include their updatable resources in the Read/Write Note API ?

If necessary, this could be made explicit, by adding after:

When used in conjunction with IS-04, the UUIDs of Resources in the Read/Write Node API MUST match those in the corresponding IS-04 Node API. The Core Resource Properties of the resources in the Read/Write Node API MUST also match the corresponding IS-04 properties.

The Read/Write Node API MUST include the Node (/self) resource and Sender and Receiver resources corresponding to all those resources in the Node API. The Read/Write Node API SHOULD (or MAY) include corresponding Source and Flow resources.

garethsb commented 1 year ago

After the rename to Annotation API, the addition would become:

The Annotation API MUST include the Node (/self) resource and Sender and Receiver resources corresponding to all those resources in the Node API. The Annotation API SHOULD (or MAY) include corresponding Source and Flow resources.

If the Node does not support annotation of e.g. Sources, the /node/sources response would be an empty array [].

Edit: Realise I forgot Device resources in the above... Should they be in the MUST sentence or the SHOULD/MAY sentence?

peterbrightwell commented 1 year ago

Action @timhall99 advise on what are the minimum expectations for the above (and also Device resources)

garethsb commented 1 year ago

@alabou on Slack:

I would exclude Flow and Sources from such requirement as they a re more likely to be dynamic and to reduce the burden on small devices.

cristian-recoseanu commented 1 year ago

@alabou on Slack:

I would exclude Flow and Sources from such requirement as they a re more likely to be dynamic and to reduce the burden on small devices.

I think we need to bring this back to use cases and how implementations actually work. I am starting to see where @alabou is coming from but I would also add that many implementations create sources and flows because they have to not because they want to. There are many implementations where the main anchor points / operational resources are the senders. This is true of most commercial controllers as well I believe since sources and flows rarely get involved in operational workflows and serve only as means to retrieve more details about what the senders are sending. I think the current ecosystem would work perfectly fine even if sources and flows didn't have labels, descriptions or tags at all.

With this in mind I think the annotation API makes more sense with resources actively used operationally whereas sources and flows generally are consumed using their unique identifiers and not directly exposed to any user facing layer.

I think this is definitely an area we need more feedback from the user community and hopefully @timhall99 can share some of his views here or on our next calls.

garethsb commented 1 year ago

Agree with your assessment of operational utility, Cristian, though would like to see annotation supported on Node and Device as well as Senders and Receivers. In which case...

The Annotation API MUST include the Node (/self), Device, Sender and Receiver resources corresponding to all resources of those types in the Node API. The Annotation API MAY include corresponding Source and Flow resources.

When the Node does not support annotation of Sources or Flows, the response to a GET request on the /node/sources or /node/flows endpoints is an empty array [].