search

radiantearth / stac-api-spec

SpatioTemporal Asset Catalog API specification - an API to make geospatial assets openly searchable and crawlable
http://stacspec.org
Apache License 2.0
220 stars 46 forks source link

Priority: child links vs. collections #388

Open m-mohr opened 1 year ago

m-mohr commented 1 year ago

In client applications such as STAC Browser we have two sources for catalogs and collections:

  1. /collections
  2. child links

I've seen implementations where the implementors want different behavior for the client:

  1. Only show collections
  2. Only show child links
  3. Merge child links and collections (which STAC Browser defaults to)

My first thought was to add a config option in STAC Browser to configure this, but on the other hand I'm wondering whether that's something that is of broader interest and may result in a new field or a set of conformance classes?

iliion commented 1 year ago

In the current implementation of STAC Browser is prioritizing to a default view., but since there are different approaches/implementations then the possibility to choose which way to go is the most sensible.

I believe this is connected with every discussion/issue concerning Browseable API

m-mohr commented 1 year ago

I think Browsable is something different, it doesn't say whether childs or collections are to be preferred, IMHO it just says that you can reach everything via links/collections that you can search for.

iliion commented 1 year ago

Exactly. My point was that no view should be prioritized over the other.

chiarch84 commented 1 year ago

Well, but the browser and whatever other software attached to the APIs needs to know which view to prioritize or it won't know what to show.

I'm not sure that adding a new field would be the best way to go. It may be too specific for the specs.

From my point of view in this part of the specs it should be suggested to put mandatory one of the following options:

  1. at least 1 child link and no data link
  2. data link and no child links
  3. data and child links together

This way it should be obvious what is the needed behavior. Then there is also the problem of the /children conformance class which might complicate even more.

iliion commented 1 year ago

At this moment collection, catalog and subcatalog are equally "seen" by the API specs, so I dont get why in the landing page there should be a link to data (aka. collections) and I am not sure where should the (sub)catalogs reside. Calling /collections should return Collections and Catalogs?

m-mohr commented 1 year ago

STAC follows Hypermedia, which basically says you can explore everything just by following links. Without having a data link you can't find the collections endpoint and as such it needs to be present (in addition to the requirement that OGC API - Features sets). If you implement OGC API - Features and STAC API - Features (or Collections) you need to have a data link. If you don't want to set it, you may need to implement another specification or extension such as the Children extension or something completely new.

The /collections endpoint can only return Collections.

What is your usecase around the (sub)catalogs? I don't quite get it, but I'm hearing it now for the second time (also from @chiarch84) and I'm somewhat confused. Could we discuss this in the next STAC community meeting? (27.2. 17:00 CET - @iliion @chiarch84 @philvarner )

chiarch84 commented 1 year ago

Here the past discussion where our usecase was explianed and where it was suggested to use the same endpointfor both collections and catalogs.

chiarch84 commented 1 year ago

To answer to this question in fact catalogs have a subset of fields of the collections, so in fact catalogs fields are also collections field. Here an example of our subcatalogs. image

m-mohr commented 1 year ago

The type field conflicts though! Otherwise, I've answered in the other issue.

chiarch84 commented 1 year ago

by the way, happy to discuss it directly in a meeting.

iliion commented 1 year ago

STAC follows Hypermedia, which basically says you can explore everything just by following links. Without having a data link you can't find the collections endpoint and as such it needs to be present (in addition to the requirement that OGC API - Features sets). If you implement OGC API - Features and STAC API - Features (or Collections) you need to have a data link. If you don't want to set it, you may need to implement another specification or extension such as the Children extension or something completely new.

The /collections endpoint can only return Collections.

What is your usecase around the (sub)catalogs? I don't quite get it, but I'm hearing it now for the second time (also from @chiarch84) and I'm somewhat confused. Could we discuss this in the next STAC community meeting? (27.2. 17:00 CET - @iliion @chiarch84 @philvarner )

yes I agree and I think I understood the situation. What you are practically saying is that there is no room for catalogs right now (although we have a working implementation).

@chiarch84 One possible solution is to return the catalogs with "type":"Collection" and consider the catalogs as collections. So the hierarchy becomes collections of collections (not in favor but it ll be implemented following the specs).

@m-mohr Maybe a /catalogs endpoint would make some sense

iliion commented 1 year ago

Ok. I just saw that STAC API Spec has also a /catalogs endpoint . Ref: https://github.com/radiantearth/stac-api-spec/tree/main/core#endpoints. The corerct way to go is to implement /children as well as /catalogs and /catalogs/catalog_id

m-mohr commented 1 year ago

What you are practically saying is that there is no room for catalogs right now (although we have a working implementation).

Yes, indeed. You can of course implement that, but it violates the spec and clients may get confused by it or may completely reject such an endpoint.

Ok. I just saw that STAC API Spec has also a /catalogs endpoint .

No, the link only specifies a proposed path for accessing specific catalogs easily, but it does NOT define a /catalogs endpoint to list all sub-catalogs. (Generally, this recommendation is not defined and explained very well, I'll open a separate issue for it. Edit: See #398)

I'm just trying to clarify misunderstandings here, I'm not sure myself what a good solution could look like, but I'm pretty sure that given the RC status of the API, it would be in an extension.

iliion commented 1 year ago

Could we discuss this in the next STAC community meeting? (27.2. 17:00 CET - @iliion @chiarch84 @philvarner )

Hi @m-mohr May i ask how to participate? Where is this meeting held?

m-mohr commented 1 year ago

@iliion It's held at https://meet.google.com/bfn-dssc-mjd