Skip to content

Commit 76b66bf

Browse files
philvarnerphilvarner
authored
Merge pull request #133 from philvarner/service-doc
add service-doc to core links table, add links diagram
2 parents 1d29ba2 + a9c0d00 commit 76b66bf

File tree

3 files changed

+166
-11
lines changed

3 files changed

+166
-11
lines changed

‎core/README.md

Lines changed: 56 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,17 @@
11
# STAC API - Core Specification
22

33
- [STAC API - Core Specification](#stac-api---core-specification)
4-
- [Potential Link Relations at `/`](#potential-link-relations-at-)
4+
- [Recommended Link Relations at `/`](#recommended-link-relations-at-)
55

66
- **OpenAPI specification:** [openapi.yaml](openapi.yaml) describes the core endpoints ([rendered version](https://api.stacspec.org/v1.0.0-beta.1/core)),
77
and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas.
88
- **Conformance URI:** <https://api.stacspec.org/v1.0.0-beta.1/core>
99
- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
1010
- **Dependencies**: None
1111

12-
The core of a STAC API is its landing page, which is the starting point to discover STAC data and what the API supports.
12+
The base of a STAC API is its landing page. This resource is the starting point to discover what behaviors the API supports via link relations.
13+
This behavior in a RESTful API is known as Hypermedia as the Engine of Application State (HATEOAS). STAC API relies heavily on hypermedia for API endpoint
14+
navigation.
1315

1416
```json
1517
{
@@ -18,23 +20,58 @@ The core of a STAC API is its landing page, which is the starting point to disco
1820
"title": "A simple STAC API Example",
1921
"description": "This Catalog aims to demonstrate the a simple landing page",
2022
"links": [
23+
{
24+
"rel": "self",
25+
"type": "application/json",
26+
"href": "https://stacserver.org"
27+
},
28+
{
29+
"rel": "root",
30+
"type": "application/json",
31+
"href": "https://stacserver.org"
32+
},
33+
{
34+
"rel": "conformance",
35+
"type": "application/json",
36+
"href": "https://stacserver.org/conformance"
37+
},
38+
{
39+
"rel": "service-desc",
40+
"type": "application/vnd.oai.openapi+json;version=3.0",
41+
"href": "https://stacserver.org/api"
42+
},
43+
{
44+
"rel": "service-doc",
45+
"type": "text/html",
46+
"href": "https://stacserver.org/api.html"
47+
},
48+
{
49+
"rel": "data",
50+
"type": "application/json",
51+
"href": "https://stacserver.org/collections"
52+
},
2153
{
2254
"rel": "child",
55+
"type": "application/json",
2356
"href": "https://stacserver.org/collections/sentinel-2",
2457
},
2558
{
2659
"rel": "child",
60+
"type": "application/json",
2761
"href": "https://stacserver.org/collections/landsat-8",
2862
},
2963
{
3064
"rel": "search",
31-
"type": "application/json",
65+
"type": "application/geo+json",
3266
"href": "https://stacserver.org/search"
3367
}
3468
],
3569
"conformsTo" : [
3670
"https://api.stacspec.org/v1.0.0-beta.1/core",
37-
"https://api.stacspec.org/v1.0.0-beta.1/item-search"
71+
"https://api.stacspec.org/v1.0.0-beta.1/item-search",
72+
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
73+
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
74+
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
3875
]
3976
}
4077
```
@@ -65,15 +102,23 @@ The root endpoint (`/`) is most useful when it presents a complete `Catalog` rep
65102
that all `Collection` and `Item` objects can be navigated to by transitively traversing links from this root. This spec does not require any
66103
API endpoints from OAFeat or STAC API to be implemented, so the following links may not exist if the endpoint has not been implemented.
67104

68-
## Potential Link Relations at `/`
105+
## Recommended Link Relations at `/`
106+
107+
![Diagram of STAC link relations](stac-api.png)
108+
109+
In each node of the diagram above, there is also a `self` and `root` link that are not depicted to keep the digram more concise.
110+
69111

70112
| **`rel`** | **href to** | **From** | **Description** |
71113
|-----------|--------------------------------------------|--------------------|------------------------------------------------------------------|
72-
| `child` | The child STAC Catalog & Collection objects | STAC Core | Provides curated paths to get to STAC Collection and Item objects |
73-
| `data` | OAFeat/OACommon `/collections` endpoint | Commons Collection | The full list of Collection objects provided by the API |
74-
| `search` | The STAC search endpoint (often `/search`) | STAC Search | Cross-collection query endpoint to select sub-sets of STAC `Item` objects |
75-
| `service-desc` | The OpenAPI description of this service | OAFeat OpenAPI | Uses the `application/vnd.oai.openapi+json;version=3.0` media type to refer to the OpenAPI 3.0 document that defines the service's API |
114+
| `root` | The root URI | STAC Core | Reference to self URI |
115+
| `self` | The root URI | OAFeat | Reference to self URI |
76116
| `conformance` | OGC `/conformance` endpoint | OAFeat / OACommon | Only required for OGC API Compliant implementations |
117+
| `service-desc` | The OpenAPI service description | OAFeat OpenAPI | Uses the `application/vnd.oai.openapi+json;version=3.0` media type to refer to the OpenAPI 3.0 document that defines the service's API |
118+
| `service-doc` | An HTML service description | OAFeat OpenAPI | Uses the `text/html` media type to refer to a human-consumable description of the service |
119+
| `data` | OAFeat/OACommon `/collections` endpoint | Commons Collection | The full list of Collection objects provided by the API |
120+
| `child` | The child STAC Catalogs & Collections | STAC Core | Provides curated paths to get to STAC Collection and Item objects |
121+
| `search` | The STAC search endpoint (often `/search`) | STAC Search | Cross-collection query endpoint to select sub-sets of STAC Item objects |
77122

78-
It is also valid to have `item` links from the landing page, but most STAC API's are used to serve up a massive amount of features, so they typically
79-
use several layers of `child` links before getting to `Item` objects.
123+
It is also valid to have `item` links from the landing page, but most STAC API's are used to serve up a large number of features, so they typically
124+
use several layers of intermediate `child` links before getting to Items.

‎core/stac-api.gv

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# All have self link to self (self edge)
2+
# All have root link to root
3+
4+
digraph g {
5+
label = <STAC API Links>;
6+
labelloc = "t";
7+
fontsize = "24"
8+
9+
graph [
10+
rankdir = "LR"
11+
];
12+
13+
node [
14+
fontsize = "16"
15+
shape = "ellipse"
16+
];
17+
18+
edge [
19+
];
20+
21+
"/" [
22+
label = "Landing Page\n/|<l9>links[rel=conformance]\l|<l8>links[rel=service-doc]\l|<l7>links[rel=service-desc]\l|<l3>links[rel=data]\l|<l4>links[rel=child]\l|<l5>links[rel=child]\l|<l6>links[rel=search]\l"
23+
shape = "record"
24+
];
25+
26+
"collections" [
27+
label = "<f0> Collections\n/collections|<c1>collections[0].links[rel=self]\l|<c2>collections[1].links[rel=self]\l"
28+
shape = "record"
29+
];
30+
31+
"collectionY" [
32+
label = "<f0> Collection y\n/collections/y|<l0>links[rel=items]\l"
33+
shape = "record"
34+
];
35+
36+
"collectionX" [
37+
label = "<f0> Collection x\n/collections/x|<l0>links[rel=items]\l"
38+
shape = "record"
39+
];
40+
41+
"service-desc" [
42+
label = "OpenAPI Spec\n/api"
43+
shape = "record"
44+
];
45+
46+
"service-doc" [
47+
label = "Service Doc\n/api.html"
48+
shape = "record"
49+
];
50+
51+
"conformance" [
52+
label = "Conformance\n/conformance"
53+
shape = "record"
54+
];
55+
56+
"collectionY-items" [
57+
label = "<f0> Collection y Items\n/collections/y/items|<f1> features[0].links[rel=self]"
58+
shape = "record"
59+
];
60+
61+
"collectionX-items" [
62+
label = "<f0> Collection x Items\n/collections/x/items|<f1> features[0].links[rel=self]"
63+
shape = "record"
64+
];
65+
66+
"collectionY-item1" [
67+
label = "<f0> Item y:1\n/collections/y/items/1|<l0>links[rel=parent]\l|<l1>links[rel=collection]\l"
68+
shape = "record"
69+
];
70+
71+
"collectionX-item1" [
72+
label = "<f0> Item x:1\n/collections/x/items/1|<l0>links[rel=parent]\l|<l1>links[rel=collection]\l"
73+
shape = "record"
74+
];
75+
76+
"item-search" [
77+
label = "<f0> Item Search\n/items|<f1>features[0].links[rel=self]\l|<f2>features[1].links[rel=self]\l"
78+
shape = "record"
79+
];
80+
81+
"/":l3 -> "collections":f0;
82+
"/":l4 -> "collectionX":f0;
83+
"/":l5 -> "collectionY":f0;
84+
"/":l6 -> "item-search":f0;
85+
"/":l7 -> "service-desc";
86+
"/":l8 -> "service-doc";
87+
"/":l9 -> "conformance";
88+
89+
"item-search":f1 -> "collectionX-item1":f0;
90+
"item-search":f2 -> "collectionY-item1":f0;
91+
92+
"collections":c2 -> "collectionY":f0;
93+
"collections":c1 -> "collectionX":f0;
94+
95+
"collectionY":l0 -> "collectionY-items":f0;
96+
"collectionY-items":f1 -> "collectionY-item1":f0;
97+
cxi2 [shape=point,width=0.01,height=0.01];
98+
cxi2 -> "collectionY":f0;
99+
"collectionY-item1":l0 -> cxi2 [dir=none];
100+
"collectionY-item1":l1 -> cxi2 [dir=none];
101+
102+
"collectionX":l0 -> "collectionX-items":f0;
103+
"collectionX-items":f1 -> "collectionX-item1":f0;
104+
cxi1 [shape=point,width=0.01,height=0.01];
105+
cxi1 -> "collectionX":f0;
106+
"collectionX-item1":l0 -> cxi1 [dir=none];
107+
"collectionX-item1":l1 -> cxi1 [dir=none];
108+
109+
110+
}

‎core/stac-api.png

135 KB
Loading

0 commit comments

Comments
 (0)