Standard Paths vs. Links

[cmheazel]

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".

[cmheazel]

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).

[joanma747]

There are two ways of using the OGC API:

• follow the paths from the landing page and discover new resources
• ready the OpenAPI document an do what you need to do.

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.

[jerstlouis]

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:
OAI/OpenAPI-Specification#1693
OAI/OpenAPI-Specification#256
OAI/OpenAPI-Specification#1363

[cmheazel]

See my comment in issue #71.
In summary: we are using "path" for two purposes. In most cases it is used as a URI - an identifier. However, we also use it as an OpenAPI element, as part of the definition of an operation. I believe that separation of these two concepts will reduce confusion and lead to a clearer, more usable standard.

See also issue #152

[jerstlouis]

@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:

• A name of each resource defined with plain identifiers (no slashes)
• A relation type defined specifically for that resource (which will not clash with other OGC API standards, maintained in OGC NA registry) for when that resource is being linked to from another resource where there is not a clear generic relative IANA-defined relationship
• A recommended fixed path relative to the attachment point (which may vary). This fixed path may or may not be required to be fixed (e.g. .../{collectionsId}/collections is fixed by Features and so I believe should also be for Common Part 2). Also maintaining a registry of these recommended paths could ensure that multiple modules can co-exist together attached to the same end-point without clashes. Not only are fixed path not incompatible with the modular blocks architecture, but I think they even help make that modular architecture possible.
• An extra column "Path is: (Fixed / Flexible)" might also be useful.

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. "self" is one which might makes sense, but even that has proven very difficult to grasp when used e.g. for each element inside the list of collections (in that case the "self" link actually points to different collections, not to the current resource URL). "parent" might also make sense in some cases. But when none of these apply, the explicit relation type defined in that table would be used. (e.g. "ogc:common:collections", "ogc:common:collection-resource", "ogc:features:items", "ogc:coverage:coverage", "ogc:coverage:domainSet").

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.

[cmheazel]

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.

[cmheazel]

@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.

[cmheazel]

@jerstlouis Fixed paths relative to the attachment point may be allowed if the membership agrees that Common Core is not required for OGC conformance.

[jerstlouis]

@cmheazel Specifically, regarding table I was talking about something like the first part of:

https://github.com/opengeospatial/ogc_api_coverages/blob/master/standard/clause_6_overview.adoc

I would find it extremely useful.

Yes, fixed paths relative to the attchment point would be great.
Specifically we have been defining two attachment points for Part 2 - Geospatial Data:

• The dataset API root
• The collection (geospatial data layer^H^H^H^H^H)

[ghobona]

2020-09-15 OGC API Cross Cutting Issues session during OGC Member Meeting

See the related resolution at #163 (comment)

[joanma747]

After duplicating the table 1 in the section 7: Overview. we will close the issue. Decided in 2020-09-28 telco.

[cmheazel]

Completed and closed.