Merge pull request #483 from joshfix/collections-post

Rework API examples page

Author: cholmes

api-spec/examples.md

@@ -3,53 +3,84 @@
 A STAC API supports both GET and POST requests. It is best to use POST when using the intersects query for two reasons:
 
 1. the size limit for a GET request is less than that of POST, so if a complex geometry is used GET may fail.
-2. The parameters for a GET request must be escaped properly, making it more difficult to construct when using JSON parameters (such as intersect)
+2. The parameters for a GET request must be escaped properly, making it more difficult to construct when using JSON 
+parameters (such as intersect)
 
 ## Core examples
 
+Requests all the items in the collection that is in New Zealand:
+
 ```
-GET /collections/{name}/items?bbox=160.6,-55.95,-170,-25.89
+GET /stac/search?bbox=160.6,-55.95,-170,-25.89
 ```
 
-Requests all the data in the collection that is in New Zealand. The filtering is made to be compatible with the STAC API,
-and the two specs seek to share the general query and filtering patterns. The key difference is that a STAC search endpoint
-will do cross collection search. A typical WFS will have multiple collections, and each will just offer search for its particular
-collection.
+Request all the items in `mycollection` that is in New Zealand:
 
-Request all the data in mycollection that is in New Zealand:
+```
+GET /stac/search/items?bbox=160.6,-55.95,-170,-25.89&collections=mycollection
+```
+
+Request 100 items in `mycollection` from New Zealand:
 
 ```
-GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89
+GET /stac/search?bbox=160.6,-55.95,-170,-25.89&limit=100&collections=mycollection
 ```
 
-Request 100 results in mycollection from New Zealand:
+Request all the items in `mycollection` that is in New Zealand from January 1st, 2019:
 
 ```
-GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&limit=100
+GET /stac/search?bbox=160.6,-55.95,-170,-25.89&time=2019-01-01&collections=mycollection
+```
+
+Request 100 items in `mycollection` or `yourcollection` that is in New Zealand from January 1st, 2019:
+
+```
+GET /stac/search?bbox=160.6,-55.95,-170,-25.89&time=2019-01-01&limit=100&collections=mycollection,yourcollection
 ```
 
-Request results 101-200 in mycollection from New Zealand:
+Request all the items in any collection that is in New Zealand from January 1st, 2019:
 
 ```
-GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&page=2&limit=100
+GET /stac/search?bbox=160.6,-55.95,-170,-25.89&time=2019-01-01
 ```
 
-Request all the data in mycollection that is in New Zealand from January 1st, 2019:
+Request all the items in any collection that is in New Zealand and has the id `1` or `2`:
 
 ```
-GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&time=2019-01-01
+GET /stac/search?bbox=160.6,-55.95,-170,-25.89&time=2019-01-01&ids=1,2
 ```
 
-Request all the data in mycollection from between January 1st and April 1st, 2019:
+Request 100 items in `mycollection` or `yourcollection` that is in New Zealand and has the id `1` or `2`:
 
 ```
-GET /collections/mycollection/items?time=2019-01-01/2019-04-01
+GET /stac/search?bbox=160.6,-55.95,-170,-25.89&time=2019-01-01&limit=100&collections=mycollection,yourcollection&ids=1,2
+```
+
+```
+POST /stac/search
+```
+
+Body:
+```json
+{
+  "bbox": [160.6, -55.95, -170, -25.89],
+  "time": "2019-01-01",
+  "limit": 100,
+  "collections": ["mycollection", "yourcollection"],
+  "ids": ["1", "2"]
+}
+```
+
+Request all the items in `mycollection` from between January 1st and April 1st, 2019:
+
+```
+GET /stac/search?time=2019-01-01/2019-04-01&collections=mycollection
 ```
 
 Request all catalog items it has that are from the second half of March, 2018 and that intersect with this area:
 
 ```
-POST /collections/mycollection/items
+POST /stac/search
 ```
 
 Body:
@@ -68,7 +99,7 @@ _Map © OpenStreetMap contributors_
 To specify a time range, use the interval syntax.
 
 ```
-POST /collections/mycollection/items
+POST /stac/search
 ```
 
 ```json
@@ -91,11 +122,30 @@ If time is a period without a start or end date, the end date is assigned to "no
 
 `P1Y2M10DT2H30M` is the same as `"P1Y2M10DT2H30M/" + new Date().toISOString()`
 
+## Querying the collections endpoint
+
+The collections endpoint does support the following query parameters to remain in alignment with WFS3:  `time`, `bbox`, 
+and `limit`.  Due to the limited parameter support, it is recommended to use the `/stac/search` endpoint for dynamic 
+STAC queries.  Some STAC implementations may choose to provide support for the full superset of STAC query parameters 
+to the collections endpoint, where the collection ID in the path variable is used as the single value in the 
+`collections` query parameter array in order to ensure the results are limited to that collection.  This is purely 
+optional and neither required nor a recommendation.
+
+Request 100 items in `mycollection` from New Zealand using the collections endpoint:
+
+```
+GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&limit=100
+```
+
+Note that the collections endpoint _only_ supports HTTP GET. HTTP POST requests are not supported.
+
 ## Extension examples
 
-The API Extensions allow for more sophisticated searching, such as the ability to search by geometries and searching on specific Item properties.
+The API Extensions allow for more sophisticated searching, such as the ability to search by geometries and searching on 
+specific Item properties.
 
-Use the *[Query](extensions/query/README.md)* extension to search for any data falling within a specific geometry collected between Jan 1st and May 1st, 2019:
+Use the *[Query](extensions/query/README.md)* extension to search for any items falling within a specific geometry 
+collected between Jan 1st and May 1st, 2019:
 
 ```
 POST /stac/search
@@ -106,15 +156,12 @@ Body:
 {
     "limit": 100,
     "intersects": {
-        "type": "Feature",
-        "geometry": {
-            "type": "Polygon",
-            "coordinates": [[
-                [-77.08248138427734, 38.788612962793636], [-77.01896667480469, 38.788612962793636],
-                [-77.01896667480469, 38.835161408189364], [-77.08248138427734, 38.835161408189364],
-                [-77.08248138427734, 38.788612962793636]
-            ]]
-        }
+        "type": "Polygon",
+        "coordinates": [[
+            [-77.08248138427734, 38.788612962793636], [-77.01896667480469, 38.788612962793636],
+            [-77.01896667480469, 38.835161408189364], [-77.08248138427734, 38.835161408189364],
+            [-77.08248138427734, 38.788612962793636]
+        ]]
     },
     "time": "2019-01-01/2019-05-01"
 }