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.

Sign up for GitHub

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

STAC API description of POST implementation #489

Merged
merged 9 commits into from
Jun 18, 2019
Merged

STAC API description of POST implementation #489

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
0fc4870
add API Spec description of POST implementation
Jun 10, 2019
c318949
readd Item after accidental removal
Jun 10, 2019
00aef64
Merge branch 'dev' into api-stac-search-post
Jun 10, 2019
02d0b38
minor corrections
Jun 11, 2019
07d47a9
fix WFS 3 Collections link
Jun 11, 2019
ab83ef2
limit: number => integer
m-mohr Jun 11, 2019
94959fd
Merge branch 'dev' into api-stac-search-post
Jun 17, 2019
e7dbfaa
prevent POST JSON for WFS 3 endpoints, clarify transaction API behavior
Jun 18, 2019
de604e5
Merge branch 'dev' into api-stac-search-post
Jun 18, 2019
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
5 changes: 3 additions & 2 deletions api-spec/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
# 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 discrepencies prior to final versions of both specifications.
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.

## In this directory

Expand Down
60 changes: 38 additions & 22 deletions api-spec/api-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,45 @@
## 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.
For WFS3-compliance, it is **required** only that `GET` is implemented for the WFS3 endpoints. Also, it is **required** only that `GET` is implemented for the STAC endpoints.

### WFS3 Endpoints
Since STAC adds additional filter parameters that may have much larger values, like `intersects`, it is **recommended** to also support `POST` for both the WFS3 and STAC endpoints that
accept filter parameters (e.g., `/collections/{collection_id}/items` and `/stac/search`).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think here we do not want to recommend supporting POST for the collections endpoints as this conflicts with the transactions extension: https://github.com/radiantearth/stac-spec/tree/master/api-spec/extensions/transaction
I believe we want to recommend that for more complex searches that require POST to exclusively use the /stac/search endpoint.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with that as to not conflict with the Transactions Ext as it is currently defined.

However, I think we should reconsider whether or not Transactions should extend the behavior of the paths defined in WFS 3. For example, what if an existing WFS 3 implementation has already implemented the GET and POST form-data operations on /collections/{collectionID}/items? I feel that if we want to provide extensions/behaviors on top of the ones defined by WFS 3 that we should duplicate the endpoints, such that, for example, we have /collections/{collectionID}/items that implements only the WFS 3 semantics, and /stac/collections/{collectionID}/items that implements our own semantics (e.g., the transactions POST behavior)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So originally, before it was an actual extension, I used PUT, PATCH, and DELETE to handle creating, updating, and deleting items against the dynamic api endpoint. I think it was during the second sprint it was decided that transactions should be executed via the collections endpoint. I'm not 100% certain why. @m-mohr is there a WFS-T3 spec that defines transactions against the collections endpoint? We also have our own catalog endpoints. Would that make more sense?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think there's as much conflict as I originally thought. I think we just needed to be explicit about the use of the application/json . See the changes in e7dbfaa

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joshfix Not yet, as far as I know, but there will probably be a WFS-T extension in the future that we could adopt.

Fine with the changes by @philvarner. Approved (again).


It is **recommended** that these `Content-Type` options be supported when using POST:

The core WFS 3 endpoints are shown below, with details provided in an [OpenAPI specification document](definitions/WFS3.yaml).
1. POST with the `Content-Type` header set to `application/x-www-form-urlencoded` with the appropriate content body format.
m-mohr marked this conversation as resolved.
Show resolved Hide resolved
2. POST with the `Content-Type` header set to `multipart/form-data` with the appropriate content body format.
3. POST with the `Content-Type` header set to `application/json`, where the content body is a JSON object with the same names as the filter parameters, as defined in the [STAC API OpenAPI specification document](STAC.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 |
| ------------ | ------------- | ---------------------- |
| / | JSON | Landing page, links to API capabilities |
| /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 |
| ------------ | ------------- | ---------------------- |
Expand All @@ -50,3 +52,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 | number | 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 | number | 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 |