Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add service-doc to core links table, add links diagram #133

Merged
merged 3 commits into from
May 17, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 56 additions & 11 deletions core/README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
# STAC API - Core Specification

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

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

The core of a STAC API is its landing page, which is the starting point to discover STAC data and what the API supports.
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.
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
navigation.

```json
{
Expand All @@ -18,23 +20,58 @@ The core of a STAC API is its landing page, which is the starting point to disco
"title": "A simple STAC API Example",
"description": "This Catalog aims to demonstrate the a simple landing page",
"links": [
{
"rel": "self",
"type": "application/json",
"href": "https://stacserver.org"
},
{
"rel": "root",
"type": "application/json",
"href": "https://stacserver.org"
},
{
"rel": "conformance",
"type": "application/json",
"href": "https://stacserver.org/conformance"
},
{
"rel": "service-desc",
"type": "application/vnd.oai.openapi+json;version=3.0",
"href": "https://stacserver.org/api"
},
{
"rel": "service-doc",
"type": "text/html",
"href": "https://stacserver.org/api.html"
},
{
"rel": "data",
"type": "application/json",
"href": "https://stacserver.org/collections"
},
{
"rel": "child",
"type": "application/json",
"href": "https://stacserver.org/collections/sentinel-2",
},
{
"rel": "child",
"type": "application/json",
"href": "https://stacserver.org/collections/landsat-8",
},
{
"rel": "search",
"type": "application/json",
"type": "application/geo+json",
"href": "https://stacserver.org/search"
}
],
"conformsTo" : [
"https://api.stacspec.org/v1.0.0-beta.1/core",
"https://api.stacspec.org/v1.0.0-beta.1/item-search"
"https://api.stacspec.org/v1.0.0-beta.1/item-search",
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
]
}
```
Expand Down Expand Up @@ -65,15 +102,23 @@ The root endpoint (`/`) is most useful when it presents a complete `Catalog` rep
that all `Collection` and `Item` objects can be navigated to by transitively traversing links from this root. This spec does not require any
API endpoints from OAFeat or STAC API to be implemented, so the following links may not exist if the endpoint has not been implemented.

## Potential Link Relations at `/`
## Recommended Link Relations at `/`

![Diagram of STAC link relations](stac-api.png)

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.


| **`rel`** | **href to** | **From** | **Description** |
|-----------|--------------------------------------------|--------------------|------------------------------------------------------------------|
| `child` | The child STAC Catalog & Collection objects | STAC Core | Provides curated paths to get to STAC Collection and Item objects |
| `data` | OAFeat/OACommon `/collections` endpoint | Commons Collection | The full list of Collection objects provided by the API |
| `search` | The STAC search endpoint (often `/search`) | STAC Search | Cross-collection query endpoint to select sub-sets of STAC `Item` objects |
| `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 |
| `root` | The root URI | STAC Core | Reference to self URI |
| `self` | The root URI | OAFeat | Reference to self URI |
| `conformance` | OGC `/conformance` endpoint | OAFeat / OACommon | Only required for OGC API Compliant implementations |
| `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 |
| `service-doc` | An HTML service description | OAFeat OpenAPI | Uses the `text/html` media type to refer to a human-consumable description of the service |
| `data` | OAFeat/OACommon `/collections` endpoint | Commons Collection | The full list of Collection objects provided by the API |
| `child` | The child STAC Catalogs & Collections | STAC Core | Provides curated paths to get to STAC Collection and Item objects |
| `search` | The STAC search endpoint (often `/search`) | STAC Search | Cross-collection query endpoint to select sub-sets of STAC Item objects |

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
use several layers of `child` links before getting to `Item` objects.
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
use several layers of intermediate `child` links before getting to Items.
110 changes: 110 additions & 0 deletions core/stac-api.gv
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# All have self link to self (self edge)
# All have root link to root

digraph g {
label = <STAC API Links>;
labelloc = "t";
fontsize = "24"

graph [
rankdir = "LR"
];

node [
fontsize = "16"
shape = "ellipse"
];

edge [
];

"/" [
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"
shape = "record"
];

"collections" [
label = "<f0> Collections\n/collections|<c1>collections[0].links[rel=self]\l|<c2>collections[1].links[rel=self]\l"
shape = "record"
];

"collectionY" [
label = "<f0> Collection y\n/collections/y|<l0>links[rel=items]\l"
shape = "record"
];

"collectionX" [
label = "<f0> Collection x\n/collections/x|<l0>links[rel=items]\l"
shape = "record"
];

"service-desc" [
label = "OpenAPI Spec\n/api"
shape = "record"
];

"service-doc" [
label = "Service Doc\n/api.html"
shape = "record"
];

"conformance" [
label = "Conformance\n/conformance"
shape = "record"
];

"collectionY-items" [
label = "<f0> Collection y Items\n/collections/y/items|<f1> features[0].links[rel=self]"
shape = "record"
];

"collectionX-items" [
label = "<f0> Collection x Items\n/collections/x/items|<f1> features[0].links[rel=self]"
shape = "record"
];

"collectionY-item1" [
label = "<f0> Item y:1\n/collections/y/items/1|<l0>links[rel=parent]\l|<l1>links[rel=collection]\l"
shape = "record"
];

"collectionX-item1" [
label = "<f0> Item x:1\n/collections/x/items/1|<l0>links[rel=parent]\l|<l1>links[rel=collection]\l"
shape = "record"
];

"item-search" [
label = "<f0> Item Search\n/items|<f1>features[0].links[rel=self]\l|<f2>features[1].links[rel=self]\l"
shape = "record"
];

"/":l3 -> "collections":f0;
"/":l4 -> "collectionX":f0;
"/":l5 -> "collectionY":f0;
"/":l6 -> "item-search":f0;
"/":l7 -> "service-desc";
"/":l8 -> "service-doc";
"/":l9 -> "conformance";

"item-search":f1 -> "collectionX-item1":f0;
"item-search":f2 -> "collectionY-item1":f0;

"collections":c2 -> "collectionY":f0;
"collections":c1 -> "collectionX":f0;

"collectionY":l0 -> "collectionY-items":f0;
"collectionY-items":f1 -> "collectionY-item1":f0;
cxi2 [shape=point,width=0.01,height=0.01];
cxi2 -> "collectionY":f0;
"collectionY-item1":l0 -> cxi2 [dir=none];
"collectionY-item1":l1 -> cxi2 [dir=none];

"collectionX":l0 -> "collectionX-items":f0;
"collectionX-items":f1 -> "collectionX-item1":f0;
cxi1 [shape=point,width=0.01,height=0.01];
cxi1 -> "collectionX":f0;
"collectionX-item1":l0 -> cxi1 [dir=none];
"collectionX-item1":l1 -> cxi1 [dir=none];


}
Binary file added core/stac-api.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.