Document filtering by type for children endpoint #8
+28
−3
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This PR proposes adding an optional `type` query parameter to the `/children` endpoint to support filtering results by resource type (e.g., `Catalog` or `Collection`). ### Motivation While the specification recommends separating different types into different hierarchy branches as a best practice, real-world data organization often results in "mixed content" folders (e.g., a Project Catalog containing both sub-project Catalogs and direct Dataset Collections). In dynamic, database-backed APIs (like those using Elasticsearch), retrieving and paginating mixed-type lists can be computationally expensive and complex to implement. Adding a standard `type` parameter allows: 1. **Backend Optimization:** Implementations can execute efficient, type-specific queries (e.g., `type: "Catalog"`) rather than fetching all children and filtering in memory. 2. **Client Flexibility:** Clients can request only the resource type they are interested in (e.g., "Show me sub-folders" vs. "Show me datasets") without receiving unwanted data. 3. **Standardization:** Prevents the proliferation of custom filter parameters (e.g., `?kind=`, `?filter=`) across different implementations. ### Proposed Change Add a section detailing the `type` parameter: #### Filtering by Type Implementations MAY support a `type` query parameter to allow clients to request a specific resource type. * `GET .../children?type=Catalog` * `GET .../children?type=Collection`
m-mohr
requested changes
Dec 8, 2025
Contributor
m-mohr
left a comment
m-mohr
left a comment
There was a problem hiding this comment.
I think I'm fine with the functionality in general, but as it's optional clients may run into issues as they don't know whether it's supported or not. As such, I'd propose to make it an optional conformance class. Something like https://api.stacspec.org/v1.0.0-rc.2/children#type-filter. Should be listed at the top and in the section.
Additionally, you'd need to update the TOC and the OpenAPI document.
m-mohr
reviewed
Dec 8, 2025
Co-authored-by: Matthias Mohr <[email protected]>
m-mohr
reviewed
Dec 8, 2025
m-mohr
reviewed
Dec 8, 2025
Co-authored-by: Matthias Mohr <[email protected]>
m-mohr
reviewed
Dec 8, 2025
Contributor
@jonhealy1 I think this^ is still open. Now that #6 is merged, the CI also fails due to the outdated TOC, I think. Can you please update this PR accordingly? Otherwise, I think it looks good. Changed the base after the merging #6 and tried to resolve the conflicts... |
Updated the section header for 'Filtering by Type' to use proper Markdown formatting.
Added 'type' query parameter to filter catalogs or collections.
Formatted parameters section for consistency.
Contributor
Author
|
@m-mohr Passing :) |
m-mohr
reviewed
Dec 10, 2025
m-mohr
reviewed
Dec 10, 2025
README.md
Outdated
Comment on lines
233
to
249
| { | ||
| "rel": "children", | ||
| "type": "application/json", | ||
| "href": "https://stac-api.example/drones/children" | ||
| }, | ||
| { | ||
| "rel": "child", | ||
| "type": "application/json", | ||
| "title": "Flight 1", | ||
| "href": "https://stac-api.example/drones/filght-1" | ||
| }, | ||
| { | ||
| "rel": "child", | ||
| "type": "application/json", | ||
| "title": "Flight 2", | ||
| "href": "https://stac-api.example/drones/flight-2" | ||
| }, |
Contributor
There was a problem hiding this comment.
The links seem to be duplicate.
Co-authored-by: Matthias Mohr <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR proposes adding an optional
typequery parameter to the/childrenendpoint to support filtering results by resource type (e.g.,CatalogorCollection).Motivation
While the specification recommends separating different types into different hierarchy branches as a best practice, real-world data organization often results in "mixed content" folders (e.g., a Project Catalog containing both sub-project Catalogs and direct Dataset Collections).
In dynamic, database-backed APIs (like those using Elasticsearch), retrieving and paginating mixed-type lists can be computationally expensive and complex to implement.
Adding a standard
typeparameter allows:type: "Catalog") rather than fetching all children and filtering in memory.?kind=,?filter=) across different implementations.Proposed Change
Add a section detailing the
typeparameter:Filtering by Type
Implementations MAY support a
typequery parameter to allow clients to request a specific resource type.GET .../children?type=CatalogGET .../children?type=CollectionRelated Issue(s):
Proposed Changes:
PR Checklist: