allow use of any service description format, but recommend OpenAPI 3.0 or 3.1 #226
Conversation
philvarner
requested review from
cholmes,
duckontheweb,
jbants,
lossyrob,
m-mohr and
matthewhanson
There was a problem hiding this comment.
To me this seems to not fully express what you've proposed in #214. Here it's sounds like it's only JSON, which must follow OpenAPI 3.0 or 3.1.
What I think it should say instead that any type (e.g. YAML) is allowed, but we recommend to support OpenAPI 3.0 or 3.1 in JSON format.
| The other HTTP verbs are not supported in STAC Item Search. The [Transaction Extension](../ogcapi-features/extensions/transaction/README.md) | ||
| does implement them, for STAC and OAFeat implementations that want to enable writing and deleting items. | ||
|
|
||
| ## Recommended Link Relations at `/` |
There was a problem hiding this comment.
this was duplicated in the prior Link Relations section
philvarner
changed the title
| | `search` | `/search` | STAC Item Search | URI for the Search endpoint | | ||
|
|
||
| The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be | ||
| OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML), |
item-search/README.md
Outdated
| | `/search` | Item Collection | Search endpoint | | ||
| | Endpoint | Returns | Description | | ||
| | --------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | ||
| | `/` | Catalog | Landing Page and root Catalog | |
There was a problem hiding this comment.
General remark: This table gets repeated quite often. Why do we need to repeat this? This is item search and as such I'd only think we need to describe search and not repeat everything fro core again...
There was a problem hiding this comment.
IIRC, it was Chris's preference that we include all the endpoints that would exist if we implemented this conformance class, not only the ones that get added by this class. The reason was that implementers may only look at this one spec, so it clearly tells them they need to implement these 3 endpoints. They may need to go look up the precise contents of / and /api in Core, but at least they know they must implement those.
m-mohr
left a comment
m-mohr
left a comment
There was a problem hiding this comment.
Added a number (of very repetitive) comments above. This PR clearly shows that the amount of repetitions is a maintenance nightmare and as such we should consider concentrating on documenting the part that actually diverge from core, I think.
| | `data` | `/collections` | OAFeat | List of Collections | | ||
|
|
||
| The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be | ||
| OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML), |
ogcapi-features/README.md
Outdated
| | `service-doc` | `/api.html` | OAFeat OpenAPI | An HTML service description. Uses the `text/html` media type to refer to a human-consumable description of the service. The path for this endpoint is only recommended to be `/api`, but may be another path. | | ||
| | **rel** | **href** | **From** | **Description** | | ||
| | ------------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `service-doc` | `/api.html` | OAFeat | An HTML service description. Uses the `text/html` media type to refer to a human-consumable description of the service. The path for this endpoint is only recommended to be `/api`, but may be another path. | |
Co-authored-by: Matthias Mohr <[email protected]>
Co-authored-by: Matthias Mohr <[email protected]>
Co-authored-by: Matthias Mohr <[email protected]>
Co-authored-by: Matthias Mohr <[email protected]>
Co-authored-by: Matthias Mohr <[email protected]>
m-mohr
left a comment
m-mohr
left a comment
There was a problem hiding this comment.
Due to vacation didn't check all the requests again and assume you did them all correctly, but approving to unblock the PR.
2 participants
Related Issue(s): #214 #228
Proposed Changes:
PR Checklist:
stac-specdirectory (these are included as a subtree and should be updated directly in radiantearth/stac-spec)