Uncertainties around /catalogs/{catalog_id}

[m-mohr]

In issue #388 (comment) I was made aware of the /catalogs/{catalog_id} recommendation. In this issue the user understood it as if /catalogs would also be a thing. This completely slipped through for me and I must say I'm also relatively confused by it. As far as I understand it's just a recommendation for where to place catalogs, but I think the definition / recommendation has flaws and issues and should maybe not be in the stable API spec as it is right now.

Why is this recommendation necessary? Thorugh the hypermedia approach in the API pre-defined paths are not really necessary. You can just follow links. If you want to give the catalogs more structure, such a recommendation is fine, but then it should be better defined and give more context. It also feels a bit like this is something that may belong more into the Children conformance class?

Anyway, if is not removed we should probably make some things more clear:

1. This is just a proposal for a path where you can find catalogs
2. There's no /catalogs endpoint defined
3. It should be made clear what relation type should be used to link to it (I assume child).
4. We may want to list the endpoint in the OpenAPI file (as optional endpoint) so that you can see an example and a schema.

[iliion]

FYI: The landing page example of the children extension implicitly suggests to retrieve catalogs through the /catalogs endpoint.

I have to say that with the current implementation of STAC API spec it is not clear how to retrieve Catalogs, therefore I think the introduction of the catalogs endpoint would be beneficial.

[m-mohr]

No, it defines /children, not /catalogs. And it uses the path structure as recommended in Core. That doesn't really imply a /catalogs endpoint to me.

IMHO Catalogs is not really an API construct, it's more a static catalog thing. You just have them for browsing (and grouping) purposes right now and as such there seems at maximum a niche use case for catalog retrieval in something like /catalogs. But let's discuss...

[philvarner]

The history of this is that when we started Browseable, there had to be some path to create the child & item links to, and /catalogs/{catalog_id} was my (hypothetical) example. I don't think there would be a /catalogs endpoint at all, only the links to the catalogs by ID.

This section was one of the ones I had in mind of extracting to a "Best Practices" document outside the spec, so I'm happy to do that.

One of the big problems with this is no one has implemented an API like this yet, so it's all hypothetical. However, we could change this description to describe a static catalog that has been indexed into an API, and the API's Landing Page child links link to the static catalog URLs? That actually seems like a more reasonable case than trying to arrange the sub-catalog hierarchy in some way that doesn't retrieve too many items in the catalog with the item links

[philvarner]

I created a PR to remove that language, as it is incomplete and confusing. I don't think we have any implementations that have successfully implemented both search and browse in an API, so this needs more work.