Concepts/components vs. concrete/literal paths

[Schpidi]

At the ESIP & OGC Sprint it came up in multiple discussions why the OAPI specs are defining concrete, literal paths like /collections, rather than the concept of a collection or component in OpenAPI. OAPI instances could use those components in their paths as needed by referencing to the published schemas like /landsat being of type collection and /landsat/data of type coverage. This would also allow OAPI instances to mix together components in their paths as needed, for example to put the STAC search concept below a collection or a coverage without violating any spec requirement.

Cc @cmheazel

[cmheazel]

The OGC API standards are organized by resource, not by path. Thus we have a section for the landing page, collections metadata, collection information metadata, etc. Each with an associated JSON schema. This is appropriate for a REST-like interface. We also describe two access patterns, hypermedia and standard paths.

That being said, we tend to discuss the APIs in terms of the paths rather than the resources. Is this a problem? After all, paths are identifiers for resources. Or does it indicate that critical concepts are not being communicated to the readers?

[joanma747]

The concepts requested starts after the collections path. To deal with Landsat "variants" we could do something like:

/collections/landsat_8_oli/all
/collections/landsat_8_tirs/all

This is beyond the OGC API Common BUT what could be discussed in "commons" i the way we do "qualified" naming mechanisms. This could result in a subclause discussing the way to do this (in the examples I'm usign "_" but this is up for discussion)

This also relate with the "collections of collections" issue.

[cmheazel]

@joanma747 What does /collections/landsat_8_oli/all return? If this is a Coverage API, then you should get back a single coverage. I expect that is not the case.

[dblodgett-usgs]

The literal paths and component-based design are really useful implementation nuances that should be helpful in teasing apart some of the sticky issues here.

@Schpidi's premise opens the door to having a generic collection component that could be used at a literal path other than “/collections”.

What this would be saying is that

1. we have a core concept: “collection” resource-type that can be extended and
2. consistent core API details and behavior for “items” who's type is specific to the collection resource type.

The requirement we need to explore further is--if an API is going to use literal paths (e.g. “/collections”), do we want to say that all resources that come from that literal path adhere to the same conformance-class(es)?

[dblodgett-usgs]

I don't know if we have clearly defined the reasoning for using literal paths in OGC API. I don't think we are going to step away from them, but maybe we should keep this issue open and get a tighter engineering decision documented for why we are making the decision to use the literal path pattern? @Schpidi -- do you feel the need to get that documented or can we close?

[cmheazel]

Status update: The API-Common standard no longer uses literal paths except for the landing page and conformance resources. Paths have been recast as URIs used within the standards to identify resources. It is recommended, but not required, that these paths be used in API implementations as well. Further refinement of the text may be needed to make this clear.

[Schpidi]

So only / and /conformance are required literally? And an implementation could use /mydata instead of /collections? Given that the implemented OAPIResource specification allows this of course. Is there any guidance of how to specify this in an API relying on OAPICommon?

[cmheazel]

@Schpidi I'll check the Users Guide to make sure this topic is covered. If not, I'll add it. I'll also make sure Parts 1 and 2 have links to the Users Guide in appropriate locations. Then this issue will be closed.

[cmheazel]

A link to the users guide has been added to part 1. There is no section in the users guide to link to at this time.

[cmheazel]

Added a link to the Users Guide in Part 2.
Added an Identifiers section to the Users Guide with initial content.

[cmheazel]

June 26, 2021 - Part 2 portion is done. Issue remains open untill Users Guide content is provided.