STAC API description of POST implementation

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.
 

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'

api-spec/STAC.yaml

@@ -683,7 +683,7 @@ components:
         - type: object
           properties:
             limit:
-              type: number
+              type: integer
               example: 10
     bbox:
       description: |

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 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`). 
+
+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        | 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 |

api-spec/openapi/STAC.yaml

@@ -291,7 +291,7 @@ components:
         - type: object
           properties:
             limit:
-              type: number
+              type: integer
               example: 10
     bbox:
       description: |