littleidiot40 / stac-federated-search Goto Github PK

In this section:
https://github.com/littleidiot40/stac-federated-search#collection-links

two approaches are mentioned. First is to use the /collections/<cid>/items endpoint in which case the requirement needs to be relaxed. I don't think this is a hard requirement (if it says "should") so having an arbitrary link there that doesn't follow the best practice for the endpoint being named /collections/<cid>/items would be fine, IMO.

However, the items endpoint is not be the best search link to use if a /search (items) endpoint is available. The reason is that /search supports POST, whereas .../items only supports GET. Additionally, some implementations may support API search extensions (query, filter, etc.) at the search endpoint but not the collections items endpoint.

This extension defines collection search, as well as federated collection and item searches.

It may be good idea to keep the collection search as separate as possible from the federated searches because at some point in the future there will be a STAC defined Collection search, in which case the federated search can just count on requiring that conformance class, like it does now with item searches.

The expected behaviour of a collection search endpoint in case the /collections endpoint returns a flat list of collections or (part of) a flat list of collections with paging links can be borrowed from API-Records ("local resources catalog" use case). However, when some of these collections are STAC collections which include rel="child" links, it is not anymore so clear what the collection search endpoint should return... Would it return any collections matching the search criteria from anywhere in the STAC collection tree ? Or is it assumed that a /records endpoint contains only (STAC) collections which are not nested ? (thus no rel="child" relations allowed in a /collections response ?). Is there a STAC requirement that all STAC collections accessible via browsing from the landing page should also appear in the /collections response, either as a flat list or with an identical nested structure (rel="child"), or can this be a subset ?. I would assume for the moment that a /collections response flattens collections in a single list which only contains a subset of all STAC collections, and cannot including rel="child" links. What do you think @littleidiot40 ?

I think some of the descriptions here could be simplified by referring to required conformance classes.

Also, the extension itself should have a conformance class that defines extension specific endpoints and parameters. Note that if this alters behavior of an existing conformance class I think that's fine, it can just replace the former class.

See https://github.com/radiantearth/stac-api-spec/blob/main/extensions.md

A potential issue with having a 'search' rel type for Collection search is that some existing implementations in the wild still have an application/json media type for the Item search (e.g., https://earth-search.aws.element84.com/v0), which would make it ambiguous with this one. pystac-client will look for either a json OR geo+json media type for a valid Item search link.

It may be cleaner to have a new rel type to represent collection search

This is really a STAC API Extension rather than a STAC extension so parts of the template used for the repo don't quite apply (e.g., JSON schema doesn't apply, there should be an OpenAPI doc fragment instead).

STAC API Extensions aren't presented as nicely, as they are all in a fragments directory. However, this is changing and we're going to moving these API Extensions into its own GitHub org just like stac-extensions so should have its own template.

Once there is a more defined structure for STAC API extensions this should be updated to follow.

Here: https://github.com/littleidiot40/stac-federated-search#landing-page

is said

When we need to distinguish between a landing Page of a "federating" catalog and a data partner catalog, we use the notation [federating]/collections or [federated]/collections.

I'm not sure I understand the cases when such a distinction needs to be made. If an API is a federated API and all results are understood to be from other APIs, is it necessary to have such a prefix on the endpoints?

Or is that an API could have both internal data as well as federated results?

Also, why two different options for the prefix: "[federating]" or "[federated]"? Are these just placeholders for some arbitrary name that links it to a specific external API?

Do we need to change/add anything to item results to achieve federated search? There are discrepancies between STAC item metadata and the CEOS BP for OpenSearch but I would argue they are more about CEOS needs than federated needs? If so, maybe a separate extension? What do you think @ycespb ?