Skip to content

Commit 92837c6

Browse files
m-mohrm-mohr
committed
Generalize /children endpoints to be usable outside of landing page #3, general rewrite/update #2 
1 parent ba8b24a commit 92837c6

File tree

1 file changed

+100
-71
lines changed

1 file changed

+100
-71
lines changed

‎README.md‎

Lines changed: 100 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -19,70 +19,87 @@
1919
- [STAC API - Core](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/core)
2020
- **Owner**: @m-mohr
2121

22-
A STAC API Landing Page (a Catalog) can return information about the Catalog and Collection child objects
23-
it contains using the link relation `children` to an endpoint `/children`. The `/children` endpoint must
24-
return the all the Catalog and Collection objects referenced by these `child` link relations.
25-
26-
The purpose of this endpoint is to present a single resource from which clients can retrieve
27-
the immediate children of a Catalog, which may be Catalog or Collection objects.
28-
While the `child` link relations in a Catalog already allow for describing these
29-
relationships, this scheme requires a client to retrieve each resource URL to find any information about
22+
A STAC API, including its Landing Page, can have links with relation type `child` that point to
23+
Catalogs and Collections. This can be used to create arbitrarily complex hierarchies similar to
24+
[static STAC catalogs](https://github.com/radiantearth/stac-spec). If APIs implement such behavior,
25+
it often also implements the [Browsable Extension](https://github.com/stac-api-extensions/browseable).
26+
The drawback of static catalogs is, that catalogs have to be traversed and a lot of requests for the
27+
children have to be executed.
28+
29+
This STAC API extension, specifies an endpoint that returns a list of all Catalog and Collection
30+
that are referenced from a Catalog or Collection with the relation type `child`.
31+
For this, it contains using the link with relation type `children` to an endpoint `/children`.
32+
The `/children` endpoint returns *all* the Catalog and Collection objects referenced by these
33+
`child` links.
34+
35+
The purpose is to provide a single resource from which clients can retrieve
36+
the *immediate* children of a Catalog or Collection in an efficient way, similar to STAC API - Collections.
37+
While the `child` link relation already allows for describing these relationships,
38+
this scheme requires a client to retrieve each resource URL to find any information about
3039
the children (e.g., title, description), which can cause significant performance issues in user-facing
3140
applications. Implementers may choose to to return only a subset of fields for each Catalog or Collection,
3241
but the objects must still be valid Catalogs and Collections.
3342

3443
## Link Relations
3544

36-
This conformance class also requires implementation of the link relations in the
37-
[STAC API - Core](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/core) conformance class.
45+
The following Link relations must exist in a Catalog or Collection with link relation type `child`:
3846

39-
The following Link relations must exist in the Landing Page (root).
47+
| rel | Media Type | From | Description |
48+
| ---------- | ------------------ | ------------------- | --------------------------------------------------- |
49+
| `children` | `application/json` | STAC API - Children | List of children of this STAC Catalog or Collection |
4050

41-
| **rel** | **href** | **From** | **Description** |
42-
| ---------- | ----------- | ------------------- | -------------------------------- |
43-
| `children` | `/children` | STAC API - Children | List of children of this catalog |
51+
The following Link relations must exist in the `/children` endpoint response:
4452

45-
The following Link relations must exist in the `/children` endpoint response.
46-
47-
| **rel** | **href** | **From** | **Description** |
48-
| ------- | ----------- | ------------------- | --------------- |
49-
| `root` | `/` | STAC Core | The root URI |
50-
| `self` | `/children` | STAC API - Children | Self reference |
53+
| rel | From | Description |
54+
| -------- | ------------------- | -------------------------------------------------------------- |
55+
| `root` | STAC Core | The langding pag (root) URI |
56+
| `parent` | STAC Core | The (parent) URI of the entity containing the `children` link. |
57+
| `self` | STAC API - Children | Self reference, i.e. the URI to the `.../children` endpoint. |
5158

5259
## Endpoints
5360

54-
This conformance class also requires for the endpoints in the
55-
[STAC API - Core](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/core) conformance class to be implemented.
61+
| Endpoint | Media Type | Description |
62+
| ------------------ | ---------------- | ------------------------------------------------------------------- |
63+
| `GET .../children` | application/json | Object with a list of Catalogs and Collections and a list of Links. |
64+
65+
The response of `GET .../children` must be a JSON object with at least two properties:
66+
67+
- `children`: An array of all child Catalogs and Collections
68+
- `link`: An array of Link Objects
5669

57-
| Endpoint | Returns | Description |
58-
| ----------- | ------- | ---------------------------------------------------- |
59-
| `/children` | JSON | Object with a list of child Catalogs and Collections |
70+
The children endpoint can occur at any depth, for example:
71+
- for a landing page (`GET /`),
72+
the children endpoint would be available at `GET /children`
73+
- for a collection available at `GET /missions/sentinel-2`,
74+
the children endpoint would be available at `GET /missions/sentinel-2/children`
75+
- for a catalog available at `GET /catalogs/{id}`,
76+
the children endpoint would be available at `GET /catalogs/{id}/children`
6077

61-
STAC APIs implementing the *STAC API - Children* conformance class must support HTTP GET operation at
62-
`/children`, with the return JSON document consisting of an array of all child Catalogs and Collections in a field `children` and an
63-
array of Links in a field `links`.
78+
Note that although the endpoint in general allows to return both Catalogs and Collections,
79+
implementations may only return a single type if the children only consist of a single type.
80+
81+
It is considered a best practice to structure the hierarchy in a way that the children for each
82+
individual request only consist of a single type.
6483

6584
## Pagination
6685

67-
The `/children` endpoint supports a pagination mechanism that aligns with pagination as described in the
68-
OGC API - Common - Part 2: Geospatial Data specification. This is described in detail in
69-
the [STAC - Features Collection Pagination section](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/ogcapi-features/README.md#collection-pagination).
70-
To the greatest extent possible, the catalog should be structured such that all children can be
71-
retrieved from the endpoint in a single call.
86+
The `/children` endpoint supports a pagination mechanism that aligns with
87+
the STAC API - Collections and Features Specification, section
88+
[Collection Pagination](https://github.com/radiantearth/stac-api-spec/blob/v1.0.0/ogcapi-features/README.md#collection-pagination).
89+
90+
To the greatest extent possible, the hierarchy should be structured such that all children can be
91+
retrieved from the endpoint in a single call without pagination.
7292

7393
## Example
7494

75-
Below is a minimal example, but captures the essence. Each object in the `children` array
76-
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),
77-
and each must have a `self` link that communicates its canonical location. And then
78-
the links section must include a `self` link, and it must also link to alternate representations
79-
(like html) of the collection.
95+
Below is a minimal example, but captures the essence.
8096

81-
The STAC API Landing Page should look like the following (note the `child` link relations):
97+
A STAC API Landing Page (`GET /`) could look like the following.
98+
Please note the `child` and `children` link relations:
8299

83100
```json
84101
{
85-
"stac_version": "1.0.0",
102+
"stac_version": "1.1.0",
86103
"id": "example-stac",
87104
"title": "A simple STAC API Example, implementing STAC API - Children",
88105
"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
96113
{
97114
"rel": "self",
98115
"type": "application/json",
99-
"href": "https://stac-api.example.com"
116+
"href": "https://stac-api.example"
100117
},
101118
{
102119
"rel": "root",
103120
"type": "application/json",
104-
"href": "https://stac-api.example.com"
121+
"href": "https://stac-api.example"
105122
},
106123
{
107124
"rel": "service-desc",
108125
"type": "application/vnd.oai.openapi+json;version=3.0",
109-
"href": "https://stac-api.example.com/api"
126+
"href": "https://stac-api.example/api"
110127
},
111128
{
112129
"rel": "service-doc",
113130
"type": "text/html",
114-
"href": "https://stac-api.example.com/api.html"
131+
"href": "https://stac-api.example/api.html"
115132
},
116133
{
117134
"rel": "children",
118135
"type": "application/json",
119-
"href": "https://stac-api.example.com/children"
136+
"href": "https://stac-api.example/children"
120137
},
121138
{
122139
"rel": "child",
123140
"type": "application/json",
124-
"href": "https://stac-api.example.com/catalogs/cool-data"
141+
"title": "Satellite Imagery",
142+
"href": "https://stac-api.example/satellites"
125143
},
126144
{
127145
"rel": "child",
128146
"type": "application/json",
129-
"href": "https://stac-api.example.com/catalogs/some-other-data"
147+
"title": "Drone Imagery",
148+
"href": "https://stac-api.example/drones"
130149
}
131150
]
132151
}
133152
```
134153

135-
The `/children` endpoint response object should look as follows:
154+
The `GET /children` endpoint response object could look as follows:
136155

137156
```json
138157
{
139158
"children": [
140159
{
141-
"stac_version": "1.0.0",
142-
"stac_extensions": [ ],
143-
"id": "cool-data",
144-
"title": "Cool Data from X Satellite",
145-
"description": "A lot of awesome words describing the data",
160+
"stac_version": "1.1.0",
161+
"id": "satellites",
162+
"title": "Satellite Imagery",
163+
"description": "This category contains data captured by satellites (currently empty).",
146164
"type": "Catalog",
147-
"license": "CC-BY",
148165
"links": [
149166
{
150167
"rel": "root",
@@ -159,26 +176,16 @@ The `/children` endpoint response object should look as follows:
159176
{
160177
"rel": "self",
161178
"type": "application/json",
162-
"href": "https://stac-api.example.com/catalogs/cool-data"
179+
"href": "https://stac-api.example.com/satellites"
163180
}
164181
]
165182
},
166183
{
167-
"stac_version": "1.0.0",
168-
"stac_extensions": [ ],
169-
"id": "some-other-data",
170-
"title": "Some Other Data from Y Satellite",
171-
"description": "More awesome words describing the data",
172-
"type": "Collection",
173-
"license": "CC-BY",
174-
"extent": {
175-
"spatial": {
176-
"bbox": [[-135.17, 36.83, -51.24, 62.25]]
177-
},
178-
"temporal": {
179-
"interval": [["2009-01-01T00:00:00Z", null]]
180-
}
181-
},
184+
"stac_version": "1.1.0",
185+
"id": "drones",
186+
"title": "Drone Imagery",
187+
"description": "This category contains data captured by drones and other airbone vehicles (from two flights).",
188+
"type": "Catalog",
182189
"links": [
183190
{
184191
"rel": "root",
@@ -190,10 +197,27 @@ The `/children` endpoint response object should look as follows:
190197
"type": "application/json",
191198
"href": "https://stac-api.example.com"
192199
},
200+
{
201+
"rel": "children",
202+
"type": "application/json",
203+
"href": "https://stac-api.example/drones/children"
204+
},
205+
{
206+
"rel": "child",
207+
"type": "application/json",
208+
"title": "Flight 1",
209+
"href": "https://stac-api.example/drones/filght-1"
210+
},
211+
{
212+
"rel": "child",
213+
"type": "application/json",
214+
"title": "Flight 2",
215+
"href": "https://stac-api.example/drones/flight-2"
216+
},
193217
{
194218
"rel": "self",
195219
"type": "application/json",
196-
"href": "https://stac-api.example.com/collections/some-other-data"
220+
"href": "https://stac-api.example.com/drones"
197221
}
198222
]
199223
}
@@ -204,6 +228,11 @@ The `/children` endpoint response object should look as follows:
204228
"type": "application/json",
205229
"href": "https://stac-api.example.com"
206230
},
231+
{
232+
"rel": "parent",
233+
"type": "application/json",
234+
"href": "https://stac-api.example.com"
235+
},
207236
{
208237
"rel": "self",
209238
"type": "application/json",

0 commit comments

Comments
 (0)