search

AMWA-TV / is-07

AMWA IS-07 NMOS Event & Tally Specification
https://specs.amwa.tv/is-07
Apache License 2.0
8 stars 6 forks source link

Trailing-slash policy inconsistency #22

Open garethsb opened 5 years ago

garethsb commented 5 years ago

https://github.com/AMWA-TV/nmos-event-tally/blob/v1.0/docs/6.0.%20Event%20and%20tally%20rest%20api.md#2-nmos-resource

For consistency the href url offered will always end with a trailing slash.

is in direct contradiction with

https://github.com/AMWA-TV/nmos-discovery-registration/blob/v1.2.1/docs/2.0.%20APIs.md#urls-approach-to-trailing-slashes

For consistency and in order to adhere to how these APIs are specified in RAML, the 'primary' path for every resource has the trailing slash omitted.

(See also https://github.com/AMWA-TV/nmos-discovery-registration/issues/87, and https://github.com/AMWA-TV/nmos-device-connection-management/issues/65.)

garethsb commented 5 years ago

It's even inconsistent with https://github.com/AMWA-TV/nmos-event-tally/blob/v1.0/docs/6.0.%20Event%20and%20tally%20rest%20api.md#7-trailing-slashes

cristian-recoseanu commented 5 years ago

Hi @garethsb-sony

The href in the controls array is not a primary path is it? It's consistent with how IS-05 v1.3 href is expressed in the controls array from here:

https://amwa-tv.github.io/nmos-device-connection-management/tags/v1.0.1/docs/3.1.Interoperability-_NMOS_IS-04.html

Unless that is wrong as well.

garethsb commented 5 years ago

The href in the controls array is not a primary path is it?

Personally, I believe it is referring to a primary path.

(Link didn't work for me, due to GitHub's rendering of underscores. This should work: https://amwa-tv.github.io/nmos-device-connection-management/tags/v1.0.1/docs/3.1._Interoperability_-_NMOS_IS-04.html.)

Unless that is wrong as well.

As noted in https://github.com/AMWA-TV/nmos-discovery-registration/issues/87, "in many cases in the documentation, examples include a trailing slash when they should not. These ought to be addressed, and the expectations placed upon clients in processing them clarified."

The important part of this is mostly to make clear that clients cannot blindly append sub-paths to a URL which may or may not end in a trailing slash.

mjeras commented 5 years ago

@garethsb-sony , do you think we should address this in the IS-07 project now, or should we start a NMOS-wide discussion on this and then address it across all projects (maybe in NMOS Core)?

garethsb commented 5 years ago

Another example in IS-07 that contradicts the usual guidance: the documentation for ext_is_07_rest_api_url says:

"For consistency the ext_is_07_rest_api_url url offered will always end with a trailing slash."