Rework API examples page #483
Conversation
api-spec/examples.md
Outdated
|
|
||
| ## Core examples | ||
|
|
||
| Requests all the data in the collection that is in New Zealand: |
There was a problem hiding this comment.
maybe call this explicitly Items rather than data -- since technically all STAC entities are metadata
| POST /stac/search | ||
| ``` | ||
|
|
||
| Body: |
There was a problem hiding this comment.
I'd prefer if we required this to be multipart/form-data instead of a JSON query body.
There was a problem hiding this comment.
I prefer that because all of the values passed to the parameters are exactly the same in the GET and POST cases. Otherwise, you have to define a separate query payload JSON schema, with similar (but not exact) mappings between values, for example, that ids is an array of strings rather than a comma-separated list of strings. With a JSON payload, we also get into the tricky situation when using the query extension where the value of one of the attributes in the JSON is a string representing another query language, e.g., CQL or GraphQL, which can expose all sorts of bugs in JSON implementations (similarly to how our use of : in extension prefixes do)
I see more APIs that use this convention. for example, https://developer.twitter.com/en/docs/tweets/search/api-reference/enterprise-search#Methods
There was a problem hiding this comment.
That would need to be filed as a separate issue. From the beginning we have used raw application/json. This examples page is examples of the current spec.
There was a problem hiding this comment.
Ah right, will do that.
There was a problem hiding this comment.
Created a PR for some explicit language around supporting POST. #489
|
This looks good to me. Like the idea of @philvarner about multipart, but agree that should be different PR. I won't merge quite yet, in case @joshfix wants to tweak the verbiage somewhat based on the suggestions by @philvarner |
Signed-off-by: Josh Fix <josh@federal.planet.com>
|
I updated the verbiage to say "items" instead of "data". Should be good to go. |
The API examples page primarily focused on dynamic queries against the
/collections/{collection_id}/itemsendpoint, which is limited to only thelimit,time, andbboxparameters. Because of the limitations, we should be driving STAC users who wish to perform dynamic queries to the/stac/searchendpoint.In this PR, the examples have been reworked to show examples against the
/stac/searchendpoint. A single example has been left to show how to query the collections endpoint and outline that the collections endpoints does not support HTTP POST.