diff --git a/README.md b/README.md index 9b45d7d..5f72c9c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,13 @@ # STAC API - Children Extension Specification -- [Overview](#overview) -- [Link Relations](#link-relations) -- [Endpoints](#endpoints) -- [Pagination](#pagination) -- [Example](#example) + +- [STAC API - Children Extension Specification](#stac-api---children-extension-specification) + - [Overview](#overview) + - [Link Relations](#link-relations) + - [Endpoints](#endpoints) + - [Pagination](#pagination) + - [Deep Traversal & Routing](#deep-traversal--routing) + - [Example](#example) ## Overview @@ -70,6 +73,23 @@ the [STAC - Features Collection Pagination section](https://github.com/radiantea To the greatest extent possible, the catalog should be structured such that all children can be retrieved from the endpoint in a single call. +## Deep Traversal & Routing + +While the primary endpoint is defined at the API Root (`/children`), this extension pattern MAY be applied to any Catalog or Collection resource within the API to enable deep, recursive traversal (similar to a file system). + +To inspect the children of a specific sub-resource, clients should append `/children` to the resource's canonical URI. + +**Examples:** +* **Root Children:** `GET /children` +* **Sub-Catalog Children:** `GET /catalogs/{id}/children` +* **Collection Children:** `GET /collections/{id}/children` (for "Collection of Collections" hierarchies) + +### Filtering by Type +Because the `children` array is polymorphic (containing both `Catalog` and `Collection` objects), implementations SHOULD support a `type` query parameter to allow clients to request a specific resource type. + +* `GET /children?type=Catalog` +* `GET /children?type=Collection` + ## Example Below is a minimal example, but captures the essence. Each object in the `children` array