From 8cbad5e0da2547dd5973da1d2c391aedf2b4d9d4 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Sun, 7 Dec 2025 16:23:10 +0100 Subject: [PATCH 1/4] Generalize /children endpoints to be usable outside of landing page #3, general rewrite/update #2 --- README.md | 171 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 100 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 9b45d7d..7fb44e4 100644 --- a/README.md +++ b/README.md @@ -19,70 +19,87 @@ - [STAC API - Core](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/core) or any later 1.x.x version - **Owner**: @m-mohr -A STAC API Landing Page (a Catalog) can return information about the Catalog and Collection child objects -it contains using the link relation `children` to an endpoint `/children`. The `/children` endpoint must -return the all the Catalog and Collection objects referenced by these `child` link relations. - -The purpose of this endpoint is to present a single resource from which clients can retrieve -the immediate children of a Catalog, which may be Catalog or Collection objects. -While the `child` link relations in a Catalog already allow for describing these -relationships, this scheme requires a client to retrieve each resource URL to find any information about +A STAC API, including its Landing Page, can have links with relation type `child` that point to +Catalogs and Collections. This can be used to create arbitrarily complex hierarchies similar to +[static STAC catalogs](https://github.com/radiantearth/stac-spec). If APIs implement such behavior, +it often also implements the [Browsable Extension](https://github.com/stac-api-extensions/browseable). +The drawback of static catalogs is, that catalogs have to be traversed and a lot of requests for the +children have to be executed. + +This STAC API extension, specifies an endpoint that returns a list of all Catalog and Collection +that are referenced from a Catalog or Collection with the relation type `child`. +For this, it contains using the link with relation type `children` to an endpoint `/children`. +The `/children` endpoint returns *all* the Catalog and Collection objects referenced by these +`child` links. + +The purpose is to provide a single resource from which clients can retrieve +the *immediate* children of a Catalog or Collection in an efficient way, similar to STAC API - Collections. +While the `child` link relation already allows for describing these relationships, +this scheme requires a client to retrieve each resource URL to find any information about the children (e.g., title, description), which can cause significant performance issues in user-facing applications. Implementers may choose to to return only a subset of fields for each Catalog or Collection, but the objects must still be valid Catalogs and Collections. ## Link Relations -This conformance class also requires implementation of the link relations in the -[STAC API - Core](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/core) conformance class. +The following Link relations must exist in a Catalog or Collection with link relation type `child`: -The following Link relations must exist in the Landing Page (root). +| rel | Media Type | From | Description | +| ---------- | ------------------ | ------------------- | --------------------------------------------------- | +| `children` | `application/json` | STAC API - Children | List of children of this STAC Catalog or Collection | -| **rel** | **href** | **From** | **Description** | -| ---------- | ----------- | ------------------- | -------------------------------- | -| `children` | `/children` | STAC API - Children | List of children of this catalog | +The following Link relations must exist in the `/children` endpoint response: -The following Link relations must exist in the `/children` endpoint response. - -| **rel** | **href** | **From** | **Description** | -| ------- | ----------- | ------------------- | --------------- | -| `root` | `/` | STAC Core | The root URI | -| `self` | `/children` | STAC API - Children | Self reference | +| rel | From | Description | +| -------- | ------------------- | -------------------------------------------------------------- | +| `root` | STAC Core | The langding pag (root) URI | +| `parent` | STAC Core | The (parent) URI of the entity containing the `children` link. | +| `self` | STAC API - Children | Self reference, i.e. the URI to the `.../children` endpoint. | ## Endpoints -This conformance class also requires for the endpoints in the -[STAC API - Core](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/core) conformance class to be implemented. +| Endpoint | Media Type | Description | +| ------------------ | ---------------- | ------------------------------------------------------------------- | +| `GET .../children` | application/json | Object with a list of Catalogs and Collections and a list of Links. | + +The response of `GET .../children` must be a JSON object with at least two properties: + +- `children`: An array of all child Catalogs and Collections +- `link`: An array of Link Objects -| Endpoint | Returns | Description | -| ----------- | ------- | ---------------------------------------------------- | -| `/children` | JSON | Object with a list of child Catalogs and Collections | +The children endpoint can occur at any depth, for example: +- for a landing page (`GET /`), + the children endpoint would be available at `GET /children` +- for a collection available at `GET /missions/sentinel-2`, + the children endpoint would be available at `GET /missions/sentinel-2/children` +- for a catalog available at `GET /catalogs/{id}`, + the children endpoint would be available at `GET /catalogs/{id}/children` -STAC APIs implementing the *STAC API - Children* conformance class must support HTTP GET operation at -`/children`, with the return JSON document consisting of an array of all child Catalogs and Collections in a field `children` and an -array of Links in a field `links`. +Note that although the endpoint in general allows to return both Catalogs and Collections, +implementations may only return a single type if the children only consist of a single type. + +It is considered a best practice to structure the hierarchy in a way that the children for each +individual request only consist of a single type. ## Pagination -The `/children` endpoint supports a pagination mechanism that aligns with pagination as described in the -OGC API - Common - Part 2: Geospatial Data specification. This is described in detail in -the [STAC - Features Collection Pagination section](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/ogcapi-features/README.md#collection-pagination). -To the greatest extent possible, the catalog should be structured such that all children can be -retrieved from the endpoint in a single call. +The `/children` endpoint supports a pagination mechanism that aligns with +the STAC API - Collections and Features Specification, section +[Collection Pagination](https://github.com/radiantearth/stac-api-spec/blob/v1.0.0/ogcapi-features/README.md#collection-pagination). + +To the greatest extent possible, the hierarchy should be structured such that all children can be +retrieved from the endpoint in a single call without pagination. ## Example -Below is a minimal example, but captures the essence. Each object in the `children` array -must be a valid STAC [Collection](https://github.com/radiantearth/stac-spec/blob/v1.0.0/collection-spec/README.md) or [Catalog](https://github.com/radiantearth/stac-spec/blob/v1.0.0/catalog-spec/README.md), -and each must have a `self` link that communicates its canonical location. And then -the links section must include a `self` link, and it must also link to alternate representations -(like html) of the collection. +Below is a minimal example, but captures the essence. -The STAC API Landing Page should look like the following (note the `child` link relations): +A STAC API Landing Page (`GET /`) could look like the following. +Please note the `child` and `children` link relations: ```json { - "stac_version": "1.0.0", + "stac_version": "1.1.0", "id": "example-stac", "title": "A simple STAC API Example, implementing STAC API - Children", "description": "This Catalog aims to demonstrate the a simple landing page", @@ -96,55 +113,55 @@ The STAC API Landing Page should look like the following (note the `child` link { "rel": "self", "type": "application/json", - "href": "https://stac-api.example.com" + "href": "https://stac-api.example" }, { "rel": "root", "type": "application/json", - "href": "https://stac-api.example.com" + "href": "https://stac-api.example" }, { "rel": "service-desc", "type": "application/vnd.oai.openapi+json;version=3.0", - "href": "https://stac-api.example.com/api" + "href": "https://stac-api.example/api" }, { "rel": "service-doc", "type": "text/html", - "href": "https://stac-api.example.com/api.html" + "href": "https://stac-api.example/api.html" }, { "rel": "children", "type": "application/json", - "href": "https://stac-api.example.com/children" + "href": "https://stac-api.example/children" }, { "rel": "child", "type": "application/json", - "href": "https://stac-api.example.com/catalogs/cool-data" + "title": "Satellite Imagery", + "href": "https://stac-api.example/satellites" }, { "rel": "child", "type": "application/json", - "href": "https://stac-api.example.com/catalogs/some-other-data" + "title": "Drone Imagery", + "href": "https://stac-api.example/drones" } ] } ``` -The `/children` endpoint response object should look as follows: +The `GET /children` endpoint response object could look as follows: ```json { "children": [ { - "stac_version": "1.0.0", - "stac_extensions": [ ], - "id": "cool-data", - "title": "Cool Data from X Satellite", - "description": "A lot of awesome words describing the data", + "stac_version": "1.1.0", + "id": "satellites", + "title": "Satellite Imagery", + "description": "This category contains data captured by satellites (currently empty).", "type": "Catalog", - "license": "CC-BY", "links": [ { "rel": "root", @@ -159,26 +176,16 @@ The `/children` endpoint response object should look as follows: { "rel": "self", "type": "application/json", - "href": "https://stac-api.example.com/catalogs/cool-data" + "href": "https://stac-api.example.com/satellites" } ] }, { - "stac_version": "1.0.0", - "stac_extensions": [ ], - "id": "some-other-data", - "title": "Some Other Data from Y Satellite", - "description": "More awesome words describing the data", - "type": "Collection", - "license": "CC-BY", - "extent": { - "spatial": { - "bbox": [[-135.17, 36.83, -51.24, 62.25]] - }, - "temporal": { - "interval": [["2009-01-01T00:00:00Z", null]] - } - }, + "stac_version": "1.1.0", + "id": "drones", + "title": "Drone Imagery", + "description": "This category contains data captured by drones and other airbone vehicles (from two flights).", + "type": "Catalog", "links": [ { "rel": "root", @@ -190,10 +197,27 @@ The `/children` endpoint response object should look as follows: "type": "application/json", "href": "https://stac-api.example.com" }, + { + "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" + }, { "rel": "self", "type": "application/json", - "href": "https://stac-api.example.com/collections/some-other-data" + "href": "https://stac-api.example.com/drones" } ] } @@ -204,6 +228,11 @@ The `/children` endpoint response object should look as follows: "type": "application/json", "href": "https://stac-api.example.com" }, + { + "rel": "parent", + "type": "application/json", + "href": "https://stac-api.example.com" + }, { "rel": "self", "type": "application/json", From d4c731e2b9afec3a05563cc5f74dad894499e2d1 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 9 Dec 2025 15:54:24 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Pete Gadomski --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7fb44e4..2907a83 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ it often also implements the [Browsable Extension](https://github.com/stac-api-e The drawback of static catalogs is, that catalogs have to be traversed and a lot of requests for the children have to be executed. -This STAC API extension, specifies an endpoint that returns a list of all Catalog and Collection +This STAC API extension specifies an endpoint that returns a list of all Catalog and Collection that are referenced from a Catalog or Collection with the relation type `child`. For this, it contains using the link with relation type `children` to an endpoint `/children`. The `/children` endpoint returns *all* the Catalog and Collection objects referenced by these @@ -52,7 +52,7 @@ The following Link relations must exist in the `/children` endpoint response: | rel | From | Description | | -------- | ------------------- | -------------------------------------------------------------- | -| `root` | STAC Core | The langding pag (root) URI | +| `root` | STAC Core | The landing page (root) URI | | `parent` | STAC Core | The (parent) URI of the entity containing the `children` link. | | `self` | STAC API - Children | Self reference, i.e. the URI to the `.../children` endpoint. | @@ -65,7 +65,7 @@ The following Link relations must exist in the `/children` endpoint response: The response of `GET .../children` must be a JSON object with at least two properties: - `children`: An array of all child Catalogs and Collections -- `link`: An array of Link Objects +- `links`: An array of Link Objects The children endpoint can occur at any depth, for example: - for a landing page (`GET /`), @@ -206,7 +206,7 @@ The `GET /children` endpoint response object could look as follows: "rel": "child", "type": "application/json", "title": "Flight 1", - "href": "https://stac-api.example/drones/filght-1" + "href": "https://stac-api.example/drones/flight-1" }, { "rel": "child", From 2c50008201398c51c98aae4f56bb48b3e8c25141 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 9 Dec 2025 15:56:31 +0100 Subject: [PATCH 3/4] .example.com -> .example --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 2907a83..10be859 100644 --- a/README.md +++ b/README.md @@ -166,17 +166,17 @@ The `GET /children` endpoint response object could look as follows: { "rel": "root", "type": "application/json", - "href": "https://stac-api.example.com" + "href": "https://stac-api.example" }, { "rel": "parent", "type": "application/json", - "href": "https://stac-api.example.com" + "href": "https://stac-api.example" }, { "rel": "self", "type": "application/json", - "href": "https://stac-api.example.com/satellites" + "href": "https://stac-api.example/satellites" } ] }, @@ -190,12 +190,12 @@ The `GET /children` endpoint response object could look as follows: { "rel": "root", "type": "application/json", - "href": "https://stac-api.example.com" + "href": "https://stac-api.example" }, { "rel": "parent", "type": "application/json", - "href": "https://stac-api.example.com" + "href": "https://stac-api.example" }, { "rel": "children", @@ -217,7 +217,7 @@ The `GET /children` endpoint response object could look as follows: { "rel": "self", "type": "application/json", - "href": "https://stac-api.example.com/drones" + "href": "https://stac-api.example/drones" } ] } @@ -226,17 +226,17 @@ The `GET /children` endpoint response object could look as follows: { "rel": "root", "type": "application/json", - "href": "https://stac-api.example.com" + "href": "https://stac-api.example" }, { "rel": "parent", "type": "application/json", - "href": "https://stac-api.example.com" + "href": "https://stac-api.example" }, { "rel": "self", "type": "application/json", - "href": "https://stac-api.example.com/children" + "href": "https://stac-api.example/children" } ] } From 306850199f466aa2f402cdd952136cff2dd0d21c Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 9 Dec 2025 20:32:43 +0100 Subject: [PATCH 4/4] Update README.md Co-authored-by: Julia Signell --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 10be859..64fca92 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ children have to be executed. This STAC API extension specifies an endpoint that returns a list of all Catalog and Collection that are referenced from a Catalog or Collection with the relation type `child`. -For this, it contains using the link with relation type `children` to an endpoint `/children`. +For this, it contains a link with relation type `children` which points to an endpoint `/children`. The `/children` endpoint returns *all* the Catalog and Collection objects referenced by these `child` links.