Principle #3a - Use Well-Known Resource Classes
cmheazel opened this issue · comments
An additional principle from the Testbed 12 REST User Guide
The title of this principle appears to be miss leading. This principle is NOT about MIME types or content negotiation.
The first, are arguably hardest, step in designing a RESTful API is to define the resources. Without a clear and coherent resource (aka data) architecture, the API will rapidly become crap. TB-12 produced an initial list of OGC Resource types. This list is incomplete, and most likely wrong. But it is a start.
In the ROA approach used in the guidelines, this principle seems a good starting point. IMHO it need to be in the start so I have moved it to #3a
I would not include the list from Testbed 12. It is not a definitive list of resources and should therefore not be part of the principle. I suggest to build the list of resources incrementally. One approach could be to register resource types that are covered by a (draft) OGC standard with the OGC NA and link to that OGC register.
I'm wondering what we consider "well-known". Terms like 'feature' and 'coverage' are not well-known outside the geospatial community. We felt we had to explain and avoid the terms in the Spatial data on the web best practices doc.
Agree with @cportele - the list should be an authoritative managed list - under the auspices of the OGC-NA (but delegated to an appropriate working group as a the register owner.
This leads to the principle that all vocabularies/terms needed for interoperability should have explicit governance and should be accessible on the Web at stable URIs as multiple machine and human readable views (as per OGC definitions server)
Note sure this issue is correctly referenced in two different places.
See the W3C work here on profiles and mime types : https://www.w3.org/TR/2018/WD-dx-prof-conneg-20181218/
now addressed in master