diff --git a/api-spec/README.md b/api-spec/README.md index 08215d64b..c1fc39bce 100644 --- a/api-spec/README.md +++ b/api-spec/README.md @@ -1,6 +1,7 @@ # STAC API -A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns STAC [Catalogs](../catalog-spec/README.md), [Collections](../collection-spec/README.md), or [Items](../item-spec/README.md), depending on the endpoint. Catalogs and Collections are JSON, while Items are GeoJSON - Features when just a single Item, or a Feature Collection when multiple Items are returned from a search. +A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC [Catalog](../catalog-spec/README.md), [Collection](../collection-spec/README.md), [Item](../item-spec/README.md), or [ItemCollection](../itemcollection-spec/README.md), depending on the endpoint. Catalogs and Collections are JSON, while Items and ItemCollections are GeoJSON-compliant entities with foreign members. Typically, a Feature is used when returning a +single Item, and FeatureCollection when multiple Items (rather than a JSON array of Item entities). The API is a [Web Feature Service 3.0 (WFS 3) API](https://github.com/opengeospatial/WFS_FES), in that WFS 3 defines many of the endpoints that STAC uses. A STAC API should be compatible and usable with WFS3 clients. However, WFS 3 is still under development and while STAC tries to stay in sync with WFS3 developments, there may be discrepancies prior to final versions of both specifications. diff --git a/api-spec/STAC-extensions.yaml b/api-spec/STAC-extensions.yaml index c0ec10708..e9dd8dc98 100644 --- a/api-spec/STAC-extensions.yaml +++ b/api-spec/STAC-extensions.yaml @@ -711,7 +711,7 @@ components: - type: object properties: limit: - type: number + type: integer example: 10 - $ref: '#/components/schemas/queryFilter' - $ref: '#/components/schemas/sortFilter' diff --git a/api-spec/STAC.yaml b/api-spec/STAC.yaml index e7db4446b..ab0803783 100644 --- a/api-spec/STAC.yaml +++ b/api-spec/STAC.yaml @@ -683,7 +683,7 @@ components: - type: object properties: limit: - type: number + type: integer example: 10 bbox: description: | diff --git a/api-spec/api-spec.md b/api-spec/api-spec.md index 2b928a648..c253daf2a 100644 --- a/api-spec/api-spec.md +++ b/api-spec/api-spec.md @@ -1,14 +1,26 @@ -## STAC API Specification +# STAC API Specification + +The STAC API is intended to be a superset of the WFS 3 API specification. The Web Feature Service is a standard API that represents collections of geospatial data. The [Web Feature Service 3.0 API](https://github.com/opengeospatial/WFS_FES), currently under development, is the latest iteration of that standard. WFS 3 defines the RESTful interface to query geospatial data, with GeoJSON as a main return type. With WFS you can return any `Feature`, which is a geometry plus any number of properties. In the STAC specification an `Item` is a `Feature`, with additional required fields for `datetime` and `assets`. WFS also defines the concept of a Collection, which contains `Feature`s. A STAC `Collection` aligns with (and extends slightly) a WFS 3 `Collection`; it contains `Item`s. -In WFS 3 Collections are the sets of data that can be queried ([7.11](https://rawgit.com/opengeospatial/WFS_FES/master/docs/17-069.html#_feature_collections_metadata)), and each describes basic information about the geospatial dataset, like its name and description, as well as the spatial and temporal extents of all the data contained. [STAC collections](../collections-spec/README.md) contain this same information, along with other STAC specific fields and thus are compliant with both WFS Collections and STAC Collections and is returned from the `/collections/{collection_id}` endpoint. +In WFS 3 Collections are the sets of data that can be queried ([7.11](http://docs.opengeospatial.org/DRAFTS/17-069r1.html#_feature_collections)), and each describes basic information about the geospatial dataset, like its name and description, as well as the spatial and temporal extents of all the data contained. [STAC collections](../collection-spec/README.md) contain this same information, along with other STAC specific fields and thus are compliant with both WFS Collections and STAC Collections and is returned from the `/collections/{collection_id}` endpoint. + +In WFS 3 Features are the individual records within a Collection and are provided in GeoJSON format. [STAC Items](../item-spec/README.md) are analogous to WFS 3 Features, are in GeoJSON, and are returned from the `/collections/{collection_id}/items/{item_id}` endpoint. + +## HTTP Request Methods and Content Types -In WFS 3 Features are the individual records within a Collection and are provided in GeoJSON format. [STAC Items](../item-spec/README.md) are analagous to WFS 3 Features, are in GeoJSON, and are returned from the `/collections/{collection_id}/items/{item_id}` endpoint. +The WFS 3 and STAC APIs follow a RESTful model. A core principal of this is the use of HTTP Request Methods (verbs) and the `Content-Type` header to drive behavior. This section describes how these are used in the WFS 3 and STAC endpoints. -### WFS3 Endpoints +1. **Required** GET (both WFS 3 and STAC) +2. **Recommended** POST `Content-Type: application/x-www-form-urlencoded` with the corresponding content body format. +3. **Recommended** POST `Content-Type: multipart/form-data` with the corresponding content body format. +4. **Optional** **STAC endpoint /stac/search only** POST `Content-Type: application/json`, where the content body is a JSON object representing a filter, as defined in the [STAC API OpenAPI specification document](STAC.yaml). +5. **Prohibited** **WFS 3 endpoints only** POST `Content-Type: application/json`, where the content body is a JSON object representing a filter. This is prohibited due to conflict with the [Transaction Extension](extensions/transaction/README.md), which defines a POST `Content-Type: application/json` operation to create an Item. -The core WFS 3 endpoints are shown below, with details provided in an [OpenAPI specification document](definitions/WFS3.yaml). +## WFS3 Endpoints + +The core WFS 3 endpoints are shown below, with details provided in an [OpenAPI specification document](openapi/WFS3.yaml). | Endpoint | Returns | Description | | ------------ | ------------- | ---------------------- | @@ -16,28 +28,15 @@ The core WFS 3 endpoints are shown below, with details provided in an [OpenAPI s | /conformance | JSON | Info about standards the API conforms to | | /collections | Collections | List of Collections contained in the catalog | | /collections/{collection_id} | Collection | Returns single Collection JSON | -| /collections/{collection_id}/items | Items | GeoJSON FeatureCollection of Items in Collection | -| /collections/{collection_id}/items/{item_id} | Item | Returns single Item GeoJSON | - -The `/collections/{collection_id}/items` endpoint accepts parameters for filtering the results (also called filters). Searching using POST will accept a JSON object where the top level keys specify which type of filter to apply (e.g., bbox=[...]). Those same key names can be used as query string parameters for the GET request. +| /collections/{collection_id}/items | ItemCollection | GeoJSON FeatureCollection-conformant entity of Items in collection | +| /collections/{collection_id}/items/{item_id} | Item | Returns single Item (GeoJSON Feature)| +The `/collections/{collection_id}/items` endpoint accepts parameters for filtering the results (also called filters). Items in the collection should match all filters to be returned when querying. This implies a logical AND operation. If an OR operation is needed, it should be specified through an extension filter. -### Filter Parameters - -| Parameter | Type | Description | -| ------------ | ------------- | ---------------------- | -| bbox | [number] | Requested bounding box [west, south, east, north] | -| time | string | Single date, date+time, or a range ('/' seperator), formatted to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6) | -| intersects | GeoJSON Geometry | Searches items by performing intersection between their geometry and provided GeoJSON geometry. All GeoJSON geometry types must be supported. | -| page | number | The page number of results. Defaults to 1 | -| limit | number | The maximum number of results to return (page size). Defaults to 10 | -| ids | [string] | Array of Item ids to return. All other filter parameters that further restrict the number of search results (except `page` and `limit`) are ignored | -| collections | [string] | Array of Collection IDs to include in the search for items. Only Items in one of the provided Collections will be searched | - ## STAC Endpoints -STAC provides some additional endpoints for the root Catalog itself, as well as the capability to search the Catalog. Note that a STAC API does not need to implement WFS 3, in which case it would only support the endpoints given below. See the [OpenAPI specification document](definitions/STAC-standalone.yaml). +STAC provides some additional endpoints for the root Catalog itself, as well as the capability to search the Catalog. Note that a STAC API does not need to implement WFS 3, in which case it would only support the endpoints given below. See the [OpenAPI specification document](openapi/STAC.yaml). | Endpoint | Returns | Description | | ------------ | ------------- | ---------------------- | @@ -50,3 +49,17 @@ The `/stac/search` endpoint is similar to the `items` endpoint in WFS3 in that i If the `/stac/search` endpoint is implemented, it is **required** to add a link with the `rel` type set to `search` to the `links` array in `GET /stac` that refers to the search endpoint in the `href` property. +## Filter Parameters + +Unless otherwise noted by **Path-only**, these filters are passed as query string, form, or JSON entity parameters. Query and form parameters should use comma-separated string values. JSON entity parameters should use JSON Arrays. + +| Parameter | Type | APIs | Description | +| ----------- | ---------------- | ---------- | ---------------------- | +| collectionId | [string] | WFS3 | **Path-only** Single Collection ID to include in the search for items. Only Items in one of the provided Collection will be searched | +| limit | integer | WFS3, STAC | The maximum number of results to return (page size). Defaults to 10 | +| bbox | [number] | WFS3, STAC | Requested bounding box [west, south, east, north] | +| time | string | WFS3, STAC | Single date, date+time, or a range ('/' seperator), formatted to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6) | +| intersects | GeoJSON Geometry | STAC | Searches items by performing intersection between their geometry and provided GeoJSON geometry. All GeoJSON geometry types must be supported. | +| page | integer | STAC | The page number of results. Defaults to 1 | +| ids | [string] | STAC | Array of Item ids to return. All other filter parameters that further restrict the number of search results (except `page` and `limit`) are ignored | +| collections | [string] | STAC | Array of Collection IDs to include in the search for items. Only Items in one of the provided Collections will be searched | diff --git a/api-spec/extensions/transaction/README.md b/api-spec/extensions/transaction/README.md index f498786c2..4f830c286 100644 --- a/api-spec/extensions/transaction/README.md +++ b/api-spec/extensions/transaction/README.md @@ -6,9 +6,9 @@ The core API doesn't support adding, editing, or removing items. The transaction ## Methods -| Path | Description | -| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `POST /collections/{collectionID}/items` | Adds a new item to a collection. | -| `PUT /collections/{collectionId}/items/{featureId}` | Updates an existing item by ID using a complete item description. | -| `PATCH /collections/{collectionId}/items/{featureId}` | Updates an existing item by ID using a partial item description, compliant with [RFC 7386](https://tools.ietf.org/html/rfc7386). | -| `DELETE /collections/{collectionID}/items` | Deletes an existing item by ID. | \ No newline at end of file +| Path | Content-Type Header | Description | +| ----------------------------------------------------- | ------------------- | ----------- | +| `POST /collections/{collectionID}/items` | `application/json` | Adds a new item to a collection. | +| `PUT /collections/{collectionId}/items/{featureId}` | `application/json` | Updates an existing item by ID using a complete item description. | +| `PATCH /collections/{collectionId}/items/{featureId}` | `application/json` | Updates an existing item by ID using a partial item description, compliant with [RFC 7386](https://tools.ietf.org/html/rfc7386). | +| `DELETE /collections/{collectionID}/items/{featureId}`| n/a | Deletes an existing item by ID. | \ No newline at end of file diff --git a/api-spec/openapi/STAC.yaml b/api-spec/openapi/STAC.yaml index 68dcb9d9f..33cd602c3 100644 --- a/api-spec/openapi/STAC.yaml +++ b/api-spec/openapi/STAC.yaml @@ -291,7 +291,7 @@ components: - type: object properties: limit: - type: number + type: integer example: 10 bbox: description: |