Skip to content

Commit

Permalink
clarify canonical, clean up recommended api url
Browse files Browse the repository at this point in the history
  • Loading branch information
@philvarner
philvarner committed Oct 5, 2021
1 parent 0078ef5 commit 0ca27fd
Show file tree
Hide file tree
Showing 4 changed files with 9 additions and 9 deletions.
2 changes: 1 addition & 1 deletion collections/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ Additionally, these relations may exist for the `/collections/{collectionId}` en

| **rel** | **href** | **From** | **Description** |
| -------- | ----------------------------------- | --------- | ------------------------------------------ |
| `canonical` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects |
| `canonical` | various | STAC Core | The child STAC Catalogs & Collections. Provides canonical paths to get to STAC Collection and Item objects if they differ from the URL that was used to retrieve the STAC object. This can be useful in federated catalogs that present data that had a different canonical location. |

Usually, the `self` link in a Collection must link to the same URL that was used to request
it. However, implementations may choose to have the canonical location of the Collection be
Expand Down
4 changes: 2 additions & 2 deletions core/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,13 @@ The following Link relations shall exist in the Landing Page (root).
| -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `root` | `/` | STAC Core | The root URI |
| `self` | `/` | OAFeat | Self reference, same as root URI |
| `service-desc` | `/api` (recommended) | OAFeat OpenAPI | The OpenAPI service description. 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-desc` | `/api` | OAFeat OpenAPI | The OpenAPI service description. 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. The path for this endpoint is only recommended to be `/api`, but may be another path. |

A `service-doc` endpoint is recommended, but not required.

| **rel** | **href** | **From** | **Description** |
| ------------- | ------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `service-doc` | `/api.html` (recommended) | OAFeat OpenAPI | An HTML service description. Uses the `text/html` media type to refer to a human-consumable description of the service |
| `service-doc` | `/api.html` | OAFeat OpenAPI | An HTML service description. Uses the `text/html` media type to refer to a human-consumable description of the service. The path for this endpoint is only recommended to be `/api.html`, but may be another path. |

Additionally, `child` relations may exist to individual catalogs and collections.

Expand Down
6 changes: 3 additions & 3 deletions item-search/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,14 +51,14 @@ The following Link relations shall exist in the Landing Page (root).
| -------------- | -------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `root` | `/` | STAC Core | The root URI |
| `self` | `/` | OAFeat | Self reference, same as root URI |
| `service-desc` | `/api` (recommended) | OAFeat OpenAPI | The OpenAPI service description. 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-desc` | `/api` | OAFeat OpenAPI | The OpenAPI service description. 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. The path for this endpoint is only recommended to be `/api`, but may be another path. |
| search | `/search` | STAC Item Search | URI for the Search endpoint |

A `service-doc` endpoint is recommended, but not required.

| **rel** | **href** | **From** | **Description** |
| ------------- | ------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `service-doc` | `/api.html` (recommended) | OAFeat OpenAPI | An HTML service description. Uses the `text/html` media type to refer to a human-consumable description of the service |
| `service-doc` | `/api.html` | OAFeat OpenAPI | An HTML service description. Uses the `text/html` media type to refer to a human-consumable description of the service. The path for this endpoint is only recommended to be `/api.html`, but may be another path. |

It is **required** to add a Link to the root endpoint (`/`) with the `rel` type set to `search`
that refers to the search endpoint in the `href` property,
Expand All @@ -82,7 +82,7 @@ Implementations that support `POST` should add a second link with the same struc
| Endpoint | Returns | Description |
| -------- | ------- | ----------- |
| `/` | Catalog | Landing Page and root Catalog |
| `/api` (recommended) | OAFeat OpenAPI | The OpenAPI service description |
| `/api` | OAFeat OpenAPI | The OpenAPI service description. The path for this endpoint is only recommended to be `/api`, but may be another path. |
| `/search` | Item Collection | Search endpoint |

## Query Parameters and Fields
Expand Down
6 changes: 3 additions & 3 deletions ogcapi-features/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,14 +45,14 @@ The following Link relations shall exist in the Landing Page (root).
| `root` | `/` | STAC Core | The root URI |
| `self` | `/` | OAFeat | Self reference, same as root URI |
| `conformance` | `/conformance` | OAFeat | Conformance URI |
| `service-desc` | `/api` (recommended) | OAFeat OpenAPI | The OpenAPI service description. 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-desc` | `/api` | OAFeat OpenAPI | The OpenAPI service description. 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. The path for this endpoint is only recommended to be `/api`, but may be another path. |
| `data` | `/collections` | OAFeat | List of Collections |

Additionally, a `service-doc` endpoint is recommended, but not required.

| **rel** | **href** | **From** | **Description** |
| ------------- | ------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `service-doc` | `/api.html` (recommended) | OAFeat OpenAPI | An HTML service description. Uses the `text/html` media type to refer to a human-consumable description of the service |
| `service-doc` | `/api.html` | OAFeat OpenAPI | An HTML service description. Uses the `text/html` media type to refer to a human-consumable description of the service. The path for this endpoint is only recommended to be `/api`, but may be another path. |

## Endpoints

Expand All @@ -62,7 +62,7 @@ The core OGC API - Features endpoints are shown below, with details provided in
| Endpoint | Returns | Description |
| ----------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `/` | [Catalog](../stac-spec/catalog-spec/README.md) | Landing page, links to API capabilities |
| `/api` | OpenAPI 3.0 JSON | Returns an OpenAPI description of the service from the `service-desc` link `rel` - not required to be `/api`, but the document is required |
| `/api` | OpenAPI 3.0 JSON | Returns an OpenAPI description of the service from the `service-desc` link `rel`. The path for this endpoint is only recommended to be `/api`, but may be another path. |
| `/conformance` | JSON | Info about standards to which the API conforms |
| `/collections` | JSON | Object containing an array of Collection objects in the Catalog, and Link relations |
| `/collections/{collectionId}` | [Collection](../stac-spec/collection-spec/README.md) | Returns single Collection JSON |
Expand Down

0 comments on commit 0ca27fd

Please sign in to comment.