STAC API description of POST implementation

api-spec/README.md

@@ -1,39 +1,40 @@
 # 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
 
 **The Specification:** The main description of the STAC API specification is in the *[api-spec.md](api-spec.md)* file. It includes an overview and in depth explanation of the REST endpoints and parameters.
 
-**Extensions:** API Extensions are given in the *[extensions](extensions/)* folder. YAML fragments are provided for each extension with details provided in the *[README](extensions/README.md)*.
+**Extensions:** API Extensions are given in the *[extensions](extensions)* folder. YAML fragments are provided for each extension with details provided in the *[README](extensions/README.md)*.
 
 **Examples:** For samples of how the STAC API can be queried, see the *[examples.md](examples.md)* file.
 
-**API Definitions:** The API is described by the OpenAPI documents in the *[openapi](openapi/)* folder.
+**API Definitions:** The API is described by the OpenAPI documents in the *[openapi](openapi)* folder.
 
 ## OpenAPI definitions
 
-The definitive specification for STAC API is provided as an [OpenAPI](http://openapis.org/) 3.0 specification that is contained within several YAML files in the [openapi](openapi/) and [extensions](extensions/) directories.
+The definitive specification for STAC API is provided as an [OpenAPI](http://openapis.org/) 3.0 specification that is contained within several YAML files in the [openapi](openapi) and [extensions](extensions) directories.
 
 These are built into the definitive core API specification at [STAC.yaml](STAC.yaml), which can be viewed online at 
 [stacspec.org/STAC-api.html](https://stacspec.org/STAC-api.html). An additional OpenAPI definition is provided at 
 [STAC-extensions.yaml](STAC-extensions.yaml) that includes all the optional extensions, and can be browsed online at
 [stacspec.org/STAC-ext-api.html](https://stacspec.org/STAC-ext-api.html).
 
-In the [openapi](openapi/) directory there are three files
+In the [openapi](openapi) directory there are three files
 
 - WFS3.yaml - The WFS3.yaml file is the WFS3 OpenAPI definition **as currently used by STAC**
 - STAC.yaml - Contains additional endpoints and components that STAC uses, which is treated as a WFS 3 extension
 - STAC.merge.yaml - A file referencing the above two used to create the final [STAC.yaml](STAC.yaml) definition
 
 A basic STAC implementation implements both the WFS3 and STAC definitions.
 
-The YAML files in the [extensions](extensions/) folder are fragments. Fragments are used to describe incomplete pieces of an OpenAPI document, and must be merged with a complete OpenAPI document to be usable. This way extensions can be kept separate, and implementors can combine just the extensions they want to use in order to create a custom OpenAPI document they can use.
+The YAML files in the [extensions](extensions) folder are fragments. Fragments are used to describe incomplete pieces of an OpenAPI document, and must be merged with a complete OpenAPI document to be usable. This way extensions can be kept separate, and implementors can combine just the extensions they want to use in order to create a custom OpenAPI document they can use.
 
-Editing should be done on the files in the [openapi](openapi/) and [extensions](extensions/) directories, *not* the `STAC.yaml` and `STAC-extensions.yaml` files, as these are automatically generated. If any of the files are edited, update the OpenAPI docs to overwrite the files:
+Editing should be done on the files in the [openapi](openapi) and [extensions](extensions) directories, *not* the `STAC.yaml` and `STAC-extensions.yaml` files, as these are automatically generated. If any of the files are edited, update the OpenAPI docs to overwrite the files:
 
 ```
 $ npm install

api-spec/api-spec.md

@@ -1,43 +1,45 @@
-## STAC API Specification
+# STAC API Specification
+
+The STAC API is intended to be a superset of the WFS 3.0 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](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](../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 only **required** that `GET` be implemented for the WFS3 endpoints.  It is also only **required** that `GET` be 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`). 
+
+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.
+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        |
 | ------------ | ------------- | ---------------------- |
@@ -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 |