diff --git a/CHANGELOG.md b/CHANGELOG.md index becb8a69..bdc4a875 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Support binding Sort, Fields, and Context Extensions to STAC Features items resource endpoint (`/collections/{collection_id}/items`) +- In Collections, added `canonical` rel type, added `/` and `/api` to list of endpoints +- In Item Search, added endpoint table ### Changed diff --git a/collections/README.md b/collections/README.md index 22afb8eb..5a2d5ced 100644 --- a/collections/README.md +++ b/collections/README.md @@ -1,12 +1,10 @@ # STAC API - Collections - [STAC API - Collections](#stac-api---collections) - - [Link Relations](#link-relations) - - [Endpoints](#endpoints) - - [Example](#example) - - [Conformance](#conformance) + - [Endpoints](#endpoints) + - [Example](#example) -- **OpenAPI specification:** Missing +- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.4/collections)) - **Conformance URI:** - **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot - **Dependencies**: [STAC API - Core](../core) @@ -21,126 +19,126 @@ Data](http://docs.opengeospatial.org/DRAFTS/20-024.html) as the [Collections req class](http://docs.opengeospatial.org/DRAFTS/20-024.html#rc_collections-section). Once the Common version is released we will aim to align with it. But it still seems to be in flux.* -## Link Relations - The following Link relations shall exist in the Landing Page (root). | **rel** | **href** | **From** | **Description** | | -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | | `data` | `/collections` | OAFeat | List of Collections | A `service-doc` endpoint is recommended, but not required. -| **rel** | **href** | **From** | **Description** | + + +| **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, these relations may exist: -Additionally, `child` relations may exist to individual catalogs and collections. | **rel** | **href** | **From** | **Description** | | -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects | -| `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects | +`child` relations are useful for supporting browsing a STAC API as if it were a static catalog. -The following Link relations should exist in the `/collections` endpoint response. +The following Link relations shall exist in the `/collections` endpoint response. | **rel** | **href** | **From** | **Description** | | ------- | -------------- | --------- | --------------- | | `root` | `/` | STAC Core | The root URI | | `self` | `/collections` | OAFeat | Self reference | -The following Link relations should exist in the `/collections/{collectionId}` endpoint response. +The following Link relations shall exist in the Collection object returned from the `/collections/{collectionId}` endpoint. | **rel** | **href** | **From** | **Description** | | -------- | ----------------------------------- | --------- | ------------------------------------------ | | `root` | `/` | STAC Core | The root URI | | `parent` | `/` | OAFeat | Parent reference, usually the root Catalog | | `self` | `/collections/{collectionId}` | OAFeat | Self reference | -| `items` | `/collections/{collectionId}/items` | OAFeat | Items within Collection | + +Additionally, these relations may exist for the `/collections/{collectionId}` endpoint: + +| **rel** | **href** | **From** | **Description** | +| -------- | ----------------------------------- | --------- | ------------------------------------------ | +| `canonical` | various | STAC Core | Provides the preferred paths to get to STAC Collection and Item objects, if they differ from the URL that was used to retrieve the STAC object and thus duplicate other content. This can be useful in federated catalogs that present metadata that has a different location than the source metadata. | + +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 +elsewhere. If this is done, it is recommended to include a `rel` of `canonical` to that location. ## Endpoints -| Endpoint | Returns | Description | -| ----------------------------- | ---------- | -------------------------------------------------------------------- | -| `/collections` | JSON | Object with a list of Collections contained in the catalog and links | -| `/collections/{collectionId}` | Collection | Returns single Collection JSON | +| Endpoint | Returns | Description | +| -------- | ------- | ----------- | +| `/` | Catalog | Landing Page and root Catalog | +| `/api` | OAFeat OpenAPI | The OpenAPI service description. The path for this endpoint is only recommended to be `/api`, but may be another path. | +| `/collections` | JSON | Object with a list of Collections contained in the catalog and links | +| `/collections/{collectionId}` | Collection | Returns single Collection JSON | STAC API's implementing the Collections class must support HTTP GET operation at `/collections`, with the return JSON document consisting of an array of all STAC Collections and an array of Links. ## Example +Below is a minimal example, but captures the essence. Each collection object must be a valid STAC +[Collection](../stac-spec/collection-spec/README.md), and each must have a `self` link that communicates its canonical location. And then +the links section must include a `self` link, and it must also link to alternate representations (like html) of the collection. + ```json { - "collections": [ - { - "stac_version": "1.0.0", - "stac_extensions": [ ], - "id": "cool-data", - "title": "Cool Data from X Satellite", - "description": "A lot of awesome words describing the data", - "type": "Collection", - "license": "CC-BY", - "extent": { - "spatial": { - "bbox": [[-135.17, 36.83, -51.24, 62.25]] - }, - "temporal": { - "interval": [["2009-01-01T00:00:00Z",null]] - } - }, - "links": [ - { - "rel": "root", - "type": "application/json", - "href": "https://myservice.com" - }, - { - "rel": "parent", - "type": "application/json", - "href": "https://myservice.com" - }, - { - "rel": "self", - "type": "application/json", - "href": "https://myservice.com/collections/cool-data" - }, - { - "rel": "items", - "type": "application/json", - "href": "https://myservice.com/collections/cool-data/items" - } - ], - } - ], - "links": [ - { - "rel": "root", - "type": "application/json", - "href": "https://myservice.com" - }, - { - "rel": "self", - "type": "application/json", - "href": "https://myservice.com/collections" - } - ] + "collections": [ + { + "stac_version": "1.0.0", + "stac_extensions": [ ], + "id": "cool-data", + "title": "Cool Data from X Satellite", + "description": "A lot of awesome words describing the data", + "type": "Collection", + "license": "CC-BY", + "extent": { + "spatial": { + "bbox": [[-135.17, 36.83, -51.24, 62.25]] + }, + "temporal": { + "interval": [["2009-01-01T00:00:00Z",null]] + } + }, + "links": [ + { + "rel": "root", + "type": "application/json", + "href": "https://myservice.com" + }, + { + "rel": "parent", + "type": "application/json", + "href": "https://myservice.com" + }, + { + "rel": "self", + "type": "application/json", + "href": "https://myservice.com/collections/cool-data" + }, + { + "rel": "items", + "type": "application/json", + "href": "https://myservice.com/collections/cool-data/items" + } + ], + } + ], + "links": [ + { + "rel": "root", + "type": "application/json", + "href": "https://myservice.com" + }, + { + "rel": "self", + "type": "application/json", + "href": "https://myservice.com/collections" + } + ] } ``` - -The above is a minimal example, but captures the essence. Each collection object must be a valid STAC -[Collection](../stac-spec/collection-spec/README.md), and each should have a `self` link that communicates its canonical location. And then -the links section must include a `self` link, and it should also link to alternate representations (like html) of the collection. - -Each collection must also be accessible from `/collections/{collectionId}`. Usually this will be the location provided by the `self` link, -but implementations may choose to list the canonical location elsewhere. But `/collections/{collectionId}` must always contain the response, -and if the canonical location is elsewhere it is recommended to include a `rel` of `canonical` from `/collections/{collectionId}` to that location. - -## Conformance - -Any implementation that provides the STAC Collection functionality described above must add `http://stacspec.org/spec/api/1.0.0-beta.4/collections`, -the conformance URI, to the `conformsTo` JSON at the landing page. - -The core STAC landing page (`/`) must also include a link with a `rel` of `data` that links to the `/collections` endpoint. - -**NOTE**: *When this aligns with OGC API - Common it will also need to add it to the `/conformance` endpoint.* diff --git a/core/README.md b/core/README.md index 4a6edd00..e23a853f 100644 --- a/core/README.md +++ b/core/README.md @@ -5,7 +5,7 @@ - [Example Landing Page for STAC API - Core](#example-landing-page-for-stac-api---core) - [Extensions](#extensions) -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) describes the core endpoints ([rendered version](https://api.stacspec.org/v1.0.0-beta.4/core)), +- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.4/core)), and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas. - **Conformance URI:** - **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot @@ -54,19 +54,20 @@ 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. + | **rel** | **href** | **From** | **Description** | | -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects | - It is also valid to have `item` links from the landing page, but most STAC API services are used to serve up a large number of features, so they typically use several layers of intermediate `child` links before getting to Item objects. Note that the `items` (plural) diff --git a/fragments/fields/README.md b/fragments/fields/README.md index 9cc0051f..5912602e 100644 --- a/fragments/fields/README.md +++ b/fragments/fields/README.md @@ -38,9 +38,9 @@ polygons can be very large when reprojected to EPSG:4326, as in the case of a hi Implementations are also not required to implement semantics for nested values whereby one can include an object, but exclude attributes of that object, e.g., include `properties` but exclude `properties.datetime`. -No error should be returned if a specified field has no value for it in the catalog. For example, if the attribute +No error must be returned if a specified field has no value for it in the catalog. For example, if the attribute "properties.eo:cloud_cover" is specified but there is no cloud cover value for an Item or the API does not even -support the EO Extension, a successful HTTP response should be returned and the Item entities will not contain that +support the EO Extension, a successful HTTP response must be returned and the Item entities will not contain that attribute. If no `fields` are specified, the response is **must** be a valid [ItemCollection](../itemcollection/README.md). If a client excludes @@ -48,7 +48,7 @@ attributes that are required in a STAC Item, the server may return an invalid ST and `geometry` are excluded, the entity will not even be a valid GeoJSON Feature, or if `bbox` is excluded then the entity will not be a valid STAC Item. -Implementations may return attributes not specified, e.g., id, but should avoid anything other than a minimal entity +Implementations may return attributes not specified, e.g., id, but must avoid anything other than a minimal entity representation. ## Include/Exclude Semantics @@ -63,7 +63,7 @@ of default properties attributes should be kept to a minimum. the `include` attributes (set difference operation). This will result in an entity that is not a valid Item if any of the excluded attributes are in the default set of attributes. 4. If both `include` and `exclude` attributes are specified, semantics are that a field must be included and **not** -excluded. E.g., if `properties` is included and `properties.datetime` is excluded, then `datetime` should not appear +excluded. E.g., if `properties` is included and `properties.datetime` is excluded, then `datetime` must not appear in the attributes of `properties`. ## Examples diff --git a/fragments/filter/README.md b/fragments/filter/README.md index b92e5633..fa5d341c 100644 --- a/fragments/filter/README.md +++ b/fragments/filter/README.md @@ -233,7 +233,7 @@ not compliant with this extension. The Queryables mechanism allows a client to discover what variable terms are available for use when writing filter expressions. These variables can be defined per-collection, and the intersection of these variables over all collections is what is available for filtering when there are no collection restrictions. These queryables are the only variables that may be used -in filter expressions, and if any variable is used in expression that is not defined as a queryable and error should be +in filter expressions, and if any variable is used in expression that is not defined as a queryable and error must be returned according to OAFeat Part 3. It is recognized that this is a severe restriction in STAC APIs that have highly variable and dynamic content. It is possible that this will change in the OAFeat Part 3 spec, see this [issue](https://github.com/opengeospatial/ogcapi-features/issues/582). For now, implementers may choose to allow @@ -341,7 +341,7 @@ supported, the server must return a 400 error if `filter-lang=cql-text`. ## Interaction with Endpoints -In an implementation that supports several operator classes, the Landing Page (`/`) should return a document including +In an implementation that supports several operator classes, the Landing Page (`/`) must return a document including at least these values: ```json diff --git a/fragments/itemcollection/README.md b/fragments/itemcollection/README.md index 5b186ccb..db69a74c 100644 --- a/fragments/itemcollection/README.md +++ b/fragments/itemcollection/README.md @@ -4,7 +4,7 @@ This document explains the structure and content of a SpatioTemporal Asset Catal An **ItemCollection** is a [GeoJSON](http://geojson.org/) [FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that is augmented with [foreign members](https://tools.ietf.org/html/rfc7946#section-6) relevant to a STAC entity. -Similarly to the relationship between a GeoJSON Feature and a STAC Item, a STAC ItemCollection should be a valid GeoJSON +Similarly to the relationship between a GeoJSON Feature and a STAC Item, a STAC ItemCollection must be a valid GeoJSON FeatureCollection to allow interoperability with existing tools that support GeoJSON. Item objects are represented in JSON format and are very flexible. Any JSON object that contains all the diff --git a/fragments/sort/README.md b/fragments/sort/README.md index a50ca2dd..7caca4d8 100644 --- a/fragments/sort/README.md +++ b/fragments/sort/README.md @@ -30,7 +30,7 @@ for the latest discussion.* ## HTTP GET (or POST Form) When calling a relevant endpoint using GET (or POST with `Content-Type: application/x-www-form-urlencoded` or -`Content-Type: multipart/form-data)`, a single parameter `sortby` with a comma-separated list of item field names should +`Content-Type: multipart/form-data)`, a single parameter `sortby` with a comma-separated list of item field names must be provided. The field names may be prefixed with either "+" for ascending, or "-" for descending. If no sign is provided before the field name, it will be assumed to be "+". diff --git a/implementation.md b/implementation.md index eb335b04..f278afed 100644 --- a/implementation.md +++ b/implementation.md @@ -70,10 +70,11 @@ RFC 3339 datetime or an interval) is: language standard libraries do not parse ISO8601 datetimes correctly, for example, the built-in Python datetime library does not handle `Z` as a timezone. -Below are a few examples of valid RFC 3339 datetimes. Note the uses of fractional seconds, the use of `.` as the fractional seconds separator, Z or z as a timezone, -positive and negative arbitrary offset timezones, and T or t as a separator between date and time. While -the RFC 3339 spec does not define the required number of fractional seconds, STAC API only requires up to -9 digits be supported. +Below are a few examples of valid RFC 3339 datetimes. Note the uses of fractional seconds, +the use of `.` as the fractional seconds separator, Z or z as a timezone, +positive and negative arbitrary offset timezones, and T or t as a separator between date and +time. While the RFC 3339 spec does not define the required number of fractional seconds, +STAC API only requires up to 9 digits be supported. - 1990-12-31T23:59:59Z (no fractional seconds, Z timezone) - 1990-12-31T23:59:23.123Z (fractional seconds, Z timezone) diff --git a/item-search/README.md b/item-search/README.md index f1e7d458..8f29f7ac 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -2,6 +2,7 @@ - [STAC API - Item Search](#stac-api---item-search) - [Link Relations](#link-relations) + - [Endpoints](#endpoints) - [Query Parameters and Fields](#query-parameters-and-fields) - [Query Examples](#query-examples) - [Query Parameter Table](#query-parameter-table) @@ -50,19 +51,19 @@ 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, with a `type` of `application/geo+json` and a `method` of `GET`. -This link should look like: +This link will look like: ```json { @@ -74,14 +75,22 @@ This link should look like: } ``` -Implementations that support `POST` should add a second link with the same structure but with a `method` of `POST`. +Implementations that support `POST` should add a second link with the same structure but with a `method` of `POST`. +## Endpoints + +| Endpoint | Returns | Description | +| -------- | ------- | ----------- | +| `/` | Catalog | Landing Page and root Catalog | +| `/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 The following list of parameters is used to narrow search queries. They can all be represented as query string parameters in a GET request, or as JSON entity fields in a POST request. For filters that represent -a set of values, query parameters should use comma-separated string values with no enclosing brackets -(\[ or \]) and no whitespace between values, and JSON entity attributes should use JSON Arrays. +a set of values, query parameters must use comma-separated string values with no enclosing brackets +(\[ or \]) and no whitespace between values, and JSON entity attributes must use JSON Arrays. ### Query Examples @@ -115,8 +124,8 @@ The core parameters for STAC search are defined by OAFeat, and STAC adds a few p See [examples](examples.md) for some example requests. -Only one of either **intersects** or **bbox** should be specified. If both are specified, a 400 Bad Request response -should be returned. +Only one of either **intersects** or **bbox** may be specified. If both are specified, a 400 Bad Request response +must be returned. **datetime** The datetime parameter use the same allowed values as the [OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter. @@ -135,7 +144,7 @@ elevation 0. ## Response -The response to a request (GET or POST) to the search endpoint should always be an +The response to a request (GET or POST) to the search endpoint must always be an [ItemCollection](../fragments/itemcollection/README.md) object - a valid [GeoJSON FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that consists entirely of STAC [Item](../stac-spec/item-spec/item-spec.md) objects. @@ -168,7 +177,7 @@ The href may contain any arbitrary URL parameter: OAFeat does not support POST requests for searches, however the STAC API spec does. Hypermedia links are not designed for anything other than GET requests, so providing a next link for a POST search request becomes problematic. STAC has -decided to extend the `link` object to support additional fields that provide hints to the client as to how it should +decided to extend the `link` object to support additional fields that provide hints to the client as to how it must execute a subsequent request for the next page of results. The following fields have been added to the `link` object specification for the API spec: @@ -176,9 +185,9 @@ The following fields have been added to the `link` object specification for the | Parameter | Type | Description | | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | method | string | The HTTP method of the request, usually `GET` or `POST`. Defaults to `GET` | -| headers | object | A dictionary of header values that should be included in the next request | -| body | object | A JSON object containing fields/values that should be included in the body of the next request | -| merge | boolean | If `true`, the headers/body fields in the `next` link should be merged into the original request and be sent combined in the next request. Defaults to `false` | +| headers | object | A dictionary of header values that must be included in the next request | +| body | object | A JSON object containing fields/values that must be included in the body of the next request | +| merge | boolean | If `true`, the headers/body fields in the `next` link must be merged into the original request and be sent combined in the next request. Defaults to `false` | The implementor has the freedom to decide exactly how to apply these extended fields for their particular pagination mechanism. The same freedom that exists for GET requests, where the actual URL parameter used to defined the next page @@ -188,7 +197,7 @@ of their choosing. Pagination can be provided solely through header values, sole combination. To avoid returning the entire original request body in a POST response which may be arbitrarily large, the `merge` -property can be specified. This indicates that the client should send the same post body that it sent in the original +property can be specified. This indicates that the client must send the same post body that it sent in the original request, but with the specified headers/body values merged in. This allows servers to indicate what needs to change to get to the next page without mirroring the entire query structure back to the client. diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index d8702b28..9e5349df 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -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 @@ -62,12 +62,12 @@ 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`. 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 | | `/collections/{collectionId}/items` | [ItemCollection](../fragments/itemcollection/README.md) | GeoJSON FeatureCollection-conformant entity of Item objects in collection | | `/collections/{collectionId}/items/{featureId}` | [Item](../stac-spec/item-spec/README.md) | Returns single Item (GeoJSON Feature) | -| `/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 | The OGC API - Features is a standard API that represents collections of geospatial data. It defines a RESTful interface to query geospatial data, with GeoJSON as a main return type. With OAFeat you can return any `Feature`, which is a geometry @@ -92,7 +92,7 @@ is outside the scope of STAC API, as the [STAC Item](../stac-spec/item-spec/item specified in GeoJSON. A typical OAFeat will have multiple collections. Simple search for items within a collection can be done -with the resource endpoint `GET /collections/{collectionId}/items`. This endpoint should be exposed via a +with the resource endpoint `GET /collections/{collectionId}/items`. This endpoint must be exposed via a link in the individual collection's endpoint with `rel=items`, as shown in the [Example Landing Page diagram](../overview.md#example-landing-page). Note that this relation is `items`, which is distinct from the `item` relation defined in STAC for linking to a single Item. The part of the API implementing OAFeat will usually not use diff --git a/ogcapi-features/extensions/version/README.md b/ogcapi-features/extensions/version/README.md index a796ae7e..aaf549fb 100644 --- a/ogcapi-features/extensions/version/README.md +++ b/ogcapi-features/extensions/version/README.md @@ -37,8 +37,8 @@ list of links to all versions available for an item. ## Version ID -Version ID is a unique identifier for a version of an item or collection. -This extension remains agnostic about what the identifier should like. +Version ID is a unique identifier for a version of an Item or Collection. +This extension remains agnostic about what the identifier should be. There are many options for a versioning schema including: - md5 hash of the record - datetime epoch