Merge pull request #133 from philvarner/service-doc

add service-doc to core links table, add links diagram
radiantearth · May 17, 2021 · 76b66bf · 76b66bf
2 parents 1d29ba2 + a9c0d00
commit 76b66bf
Show file tree

Hide file tree

Showing 3 changed files with 166 additions and 11 deletions.
diff --git a/core/README.md b/core/README.md
@@ -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
 {
@@ -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"
     ]
 }
 ```
@@ -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.
diff --git a/core/stac-api.gv b/core/stac-api.gv
@@ -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];
+
+
+}
diff --git a/core/stac-api.png b/core/stac-api.png