HTTP additions for links

[m-mohr]

In STAC API spec we have additional properties for links:

• method
• headers
• body
• (merge)

At least the method should be added to stac-spec as it could be helpful to specify e.g. the method for links (e.g. POST vs GET search or in https://github.com/stac-extensions/order/issues/9). headers and body could also be added as a general framework for HTTP requests. I think merge only makes sense in the specific API context.

They are described here (weirdly hidden in the Pagination section): https://github.com/radiantearth/stac-api-spec/blob/604ade6158de15b8ab068320ca41e25e2bf0e116/item-search/README.md#pagination (scroll down to the table)

[m-mohr]

Wait for #1199 to be merged, then we can fix it in a single location.

[m-mohr]

Might also be useful for assets? The GEE data seems to be only available via POST: https://matrix.to/#/!keYKZtlQXulQARQNzG:gitter.im/$Fa4N2N4_lkf0U3g-GKVsQwX_vO4R4yDxvaKH5e202M4?via=gitter.im&via=matrix.org&via=chard.com

[ycespb]

We have an additional use case (for method="POST"), where we are using a STAC asset to provide an (OGC kind-of) offering allowing to "order" (make the product available "online") via an ordering URL. The "order" is done via a link and method="POST" (with an empty/optional payload) and we would expose this I/F as a STAC asset as shown below.

---

"offering_1": {
  "method": "POST",
  "roles": [
    "order"
  ],
  "href": "https://..../.../v1/Products(42d16f44-f4f1-64f6-9fad-a14e68bcef9e)/Order",
  "title": "Order",
  "type": "application/json"
},

---

[ycespb]

It would be nice if the link properties could be extended to allow for templated links as proposed by https://docs.ogc.org/DRAFTS/20-004.html#sc_templated_links_with_variables. An collection asset representing an OGC WCS offering (GetCoverage) could then be provided with the allowed parameters and a client application (STACBrowser) can then replace them with actual values based on user choices.

[m-mohr]

@ycespb Templated links are blocked by https://github.com/opengeospatial/ogcapi-records/issues/275#issue-1731925116 and related issues in OGC.

[m-mohr]

Yet another use case is the example-links extension: https://github.com/stac-extensions/example-links#fields

Drawback: Implementing such links in browser is not trivial. You can't easily create a POST request, an <a> tag can only issue GET requests. You can only use the <form> tag or issue requests via JS. JS requests though you can't usually render in the browser without further actions.

[gadomski]

I'm 👍🏼 from the implementation side. I found it most natural to pull the HTTP methods into my core Link structure for stac-rs: https://docs.rs/stac/0.5.0/stac/link/struct.Link.html#structfield.method. To me, that indicates that those fields belong down at the spec level.

[m-mohr]

Agreed to add method, headers and body as defined in the API spec to align both specs.