-
Notifications
You must be signed in to change notification settings - Fork 14
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Standard Paths vs. Links #60
Comments
Consider a capabilities approach to paths. If you are hosting the API description on the landing page then it shall be found on the /api path. If the resources you are exposing are organized into one or more collections, then they shall be accessible through the /collections path. The /conformance path is required. Note that you don't have to use /collections if it is inappropriate for your resource type (ex. styles). |
There are two ways of using the OGC API:
The first option is for the web based tools that know nothing about OGC. I thing there is a value in considering this and it is not so difficult to support it. This discussion has been already done in OGC API Features. |
I strongly the support the "standard path" approach, for a generic client to neither have to parse the OpenAPI document (high complexity level, especially if OpenAPI are not a common thing for your development platform), nor "follow the link" (saving number of requests). Furthermore, it would be great if a service could amalgamate a document from standard OpenAPI fragments corresponding to the conformance classes it supports, without having to generate it. This would in turn benefit from being able to externally specify the variable portion (e.g. valid enumeration parameter values?) separately. This would work if OpenAPI could support templated $ref to describe the enumeration values (or numerical constraints? e.g. valid tile row/col) Related OpenAPI issues: |
See my comment in issue #71. See also issue #152 |
@cmheazel Using paths as a URI but not implying the path might add to the confusion... I would suggest including a table early on in each of the modular standard specifications with:
As I hinted above in some cases it might facilitate implementation for some resources to have a fixed path, so as to avoid both extra server round-trips and the complexity of parsing an OpenAPI document. Regarding the second point, I understand that the relation type approach is focused on the relation relative from one resource to another. However in practice, I think the tradtionally used relationships are proving to be inadequate to describe the complex structure of OGC APIs. Common could probably clarify specific IANA relationships which may apply between diferrent types of resources and for what purposes they should be used. I think the bottom line is that for complex APIs, relation types explicitly telling you where you're going to land are actually much easier to grasp and easier to implement than trying to make this a relative relation type, much like absolute vs. relative paths. |
Each requirement dealing with the access of a resource requires that the appropriate relation types and standard paths (if any) are exercised and that they return the required response. |
@jerstlouis Such a table would be very dense and hard to use. The current table structure provides you with the resource identifiers and a link to the details about that resource. An additional table could be added to each resource section to provide the level of detail you describe, but only for that resource. |
@jerstlouis Fixed paths relative to the attachment point may be allowed if the membership agrees that Common Core is not required for OGC conformance. |
@cmheazel Specifically, regarding table I was talking about something like the first part of: I would find it extremely useful. Yes, fixed paths relative to the attchment point would be great.
|
2020-09-15 OGC API Cross Cutting Issues session during OGC Member Meeting See the related resolution at #163 (comment) |
After duplicating the table 1 in the section 7: Overview. we will close the issue. Decided in 2020-09-28 telco. |
Completed and closed. |
Spacebel comment in the API Hackathon ER
The OGC API specifications are imposing to advertise "paths" in the Landing Page response and also contain wording suggesting that actual path names such as "api", "conformance", "collections" are mandatory and not just examples. This should be made clearer and it seems redundant to impose the declaration of paths in the landing page if indeed the path names are "fixed".
The text was updated successfully, but these errors were encountered: