Add link template for Feature resources to the Collection

[cportele]

Raised by @IvanSanchez in the July 2022 Code Sprint while developing a client for Part 4:

The feature URIs are unambiguously specified in Part 1, but it would be good for clients to have an explicit link template for the Feature resources in the Collection resource. This is in particular relevant for Part 4 where clients frequently interact with individual features. So something like:

{ 
  "rel": "item", 
  "title": "Link template for features", 
  "href": "https://www.example.com/path/to/api/v1/collections/buildings/items/{featureId}", 
  "templated": true, 
  "varBase": "https://www.opengis.net/def/vars/ogc/0/" 
}

Note that "varBase" is inspired by the Link Template ID and the value implies that there is a register in the OGC definition server for such variables. In this case featureId would be described at https://www.opengis.net/def/vars/ogc/0/featureId.

With regard to the link relation type, since it is a template and not a proper link, it should not be "item", but something else?

[jerstlouis]

Happy to see this being raised again as I had raised the same issue identified during compliance testing with the ETS.

"item" is used for the templated links in Tiles (items of the tileset), and we also already use "item" as well in our Features implementation for these featureId templated links, e.g.:

{
   "rel" : "item",
   "type" : "application/geo+json",
   "title" : "ne_10m_admin_0_countries (individual feature as GeoJSON)",
   "href" : "/ogcapi/collections/NaturalEarth:cultural:ne_10m_admin_0_countries/items/{featureId}.json",
   "templated" : true
},

Note that in OGC API - Tiles we used varBase (camelCase) in recommendation 4.

[cportele]

Thanks for the reminder, I now remember that we agreed to use varBase in Tiles 😄. I updated the example in the opening comment.

It is still important to understand that this link template would be just for client convenience. The URI in href is fully specified by the requirements in Part 1 and an implementation cannot just use a different URI. A test suite should not rely on the link template, but follow the requirements in Part 1.

[jerstlouis]

@cportele Yes, I understand that Features specifies (req 32) a fixed path of /items/{featureId} (which a client / test suite can rely on), and that an API definition would document.
And that the reliable mechanism for content negotiate is the Accept: header (rather than ?f=json or .json).

Yes, it is for client convenience, but convenience in the context of consistency with the overall OGC API approach of supporting both "follow the links" and "API definition" ways of discovering path resources. There was no way to get to individual items following links.

"Fixed paths" really is yet a third approach for client to know where to access resources, that is required for some OGC API resources (most of them except for the location of the API definition in Features). In other specifications, other resources are not required at a fixed path (e.g., the tiles and tilesets resources in OGC API - Tiles could be anywhere, even hosted on a separate server like cheap cloud object storage -- therefore clients need to either follow links, or recognize operationID prefixes in the OpenAPI definition if the service implements Tiles/OAS30 conformance class).

Unlike the other two approaches which can be discovered organically, the only way to learn about "Fixed paths" is by reading the specification. One cannot know from looking at one API implementation/deployment that the same path will work with other implementations/deployments.

[cportele]

@jerstlouis - I agree that it would be good to add the link template, but the "two approaches" are this:

Implementations of OGC API Features are intended to support two different approaches how clients can use the API.

In the first approach, clients are implemented with knowledge about this standard and its resource types. The clients navigate the resources based on this knowledge and based on the responses provided by the API. The API definition may be used to determine details, e.g., on filter parameters, but this may not be necessary depending on the needs of the client. These are clients that are in general able to use multiple APIs as long as they implement OGC API Features.

The other approach targets developers that are not familiar with the OGC API standards, but want to interact with spatial data provided by an API that happens to implement OGC API Features. In this case the developer will study and use the API definition - typically an OpenAPI document - to understand the API and implement the code to interact with the API. This assumes familiarity with the API definition language and the related tooling, but it should not be necessary to study the OGC API standards.

Links (and link templates) are important in general since these are Web APIs and linking is fundamental in the architecture of the web. But that clients will use the links is only one aspect how the first approach can be supported.

To use fixed paths for the resources in Features (except for the API definition) was a conscious design decision to make APIs more predictable for client developers and I still think it was the right decision. For the API definition or for the Tile resources it does make sense to allow more flexibility because of the existing ways that API definitions or tilesets are already published on the web.

[jerstlouis]

@cportele

To use fixed paths for the resources in Features (except for the API definition) was a conscious design decision to make APIs more predictable for client developers and I still think it was the right decision

I don't disagree.

but the "two approaches" are this:

It seems that this might have been absorbed and slightly metamorphosed into different flavors of two approaches e.g., Tiles says this:

There are at least two ways to approach an OGC API.

• Read the landing page, look for links, follow them and discover new links until the desired resource is found
• Read a Web API definition document that will specify a list of paths and path templates to resources.

For the first approach, many resources in the Web API include links with rel properties to know the reason and purpose for this relation.

For the second approach, implementations should consider the Requirement Class "OpenAPI Specification 3.0" API definition which specifies the use of operationID suffixes, providing a mechanism to associate API paths with the requirements class that they implement.

There is yet a third way to approach an OGC API that relies on assuming a set of predefined paths and path templates. These predefined paths are used in many examples in this document and are presented together in Table 8.

Same two approaches in our Quickstart Guide for Clients (Follow the links and API approach)

Regarding:

But that clients will use the links is only one aspect how the first approach can be supported.

I think that first approach mentioned in Features is closest to that third approach in Tiles.
The first (Tiles) approach follow the link that does not require either knowledge of OGC specifications nor of a particular API definition language is not mentioned in Features.

But because several OGC API resources do not have a fixed path, I think in practice follow the link is really what clients need to implement in several places, so being able to consistently use that approach to get to every resource is really a good idea to avoid surprising client developers who come to expect this. This is also well illustrated by Joan's nice API exploration graphs.

[cportele]

Meeting 2022-09-12: This issue is related to part 1 and should be addressed there (with a recommendation for now). @cportele will create a PR.