add qualification on items POST

[tomkralidis]

As mentioned on Gitter:

Considering a server that implements both Part 3 and Part 4, how do servers supposed to delineate between an .../items POST transaction (Create) and an .../items POST query (CQL2)?

There doesn't seem to be any guidance on POST and CQL2 JSON in Part 3 currently. Sending CQL2 JSON via GET can be error prone.

As suggested by @m-mohr, what about adding a media type as part of Part 3? Example:

curl -X 'POST' \
  'http://localhost:5000/collections/canada-metadata/items' \
  -H 'accept: */*' \
  -H 'Content-Type: application/cql2+json' \
  -d '{
  "op": "=",
  "args": [
    {
      "property": "title"
    },
    "Lorem ipsum"
  ]
}'

[m-mohr]

I'd like to second that. It would also be helpful for our Collection Search Extension we added to STAC during the OGC Metadata sprint.

[pvretano]

There is no POST behaviour defined in Part 3. Part 3 defines the query parameters filter, filter-lang and filter-crs which are attached to the /items endpoint when using the GET method.

There is a proposal for using POST for query/search here: https://github.com/opengeospatial/ogcapi-features/tree/master/proposals/search

Basically there is a /collections/{collectionId}/search endpoint defined to which you can POST a query such as:

{
  "filter": {
    "op": "and",
    "args": [
      { "op": "=", "args": [{ "property": "composition" }, "CONC"] },
      { "op": "in", "args": [{ "property": "airport" }, ["JFK", "EWR", "LGA"]] }
    ]
  },
  "properties": ["geometry", "airport", "type"],
  "sortby": ["airport"],
  "limit": 1000
}

Not sure if you will be able to see this but there is also this issue in TB18: https://gitlab.ogc.org/ogc/T18-Advanced_Filtering_of_SWIM_Feature_Data/-/issues/11

[tomkralidis]

What's the rationale of /collections/{collectionId}/search POST vs /collections/{collectionId}/items POST? I'm guessing we do not want to overload the responsibilities of the latter?

[m-mohr]

How would you do POSt for collections?

[cportele]

The decision/agreement to use "/search" as the path element for query resources dates back to the March 2018 Code Sprint / Hackathon with STAC, at least for multi-collection queries. Whether there is also a general need for query resources per collection is a topic for discussion.

I think this issue is a duplicate of #449? See also the discussion in that issue.

[francbartoli]

I'd like the HTTP QUERY method. It is not yet supported by the OpenAPI specification though as mentioned here

[jampukka]

I'd avoid having multiple responsibilities for single method + path combination, at least for now. QUERY /collections/{collectionId}/items would be ideal as it captures what the user is trying to achieve and it doesn't interfere with POST /collections/{collectionId}/items which Part 4 CRUD certainly has a "claim" for. The problem with QUERY is that it doesn't exist here today.

Personally I feel like Part 3 is already overdue and would prefer if it could be finished sooner rather than later. I'd say adding too little per extension is better than too much if it adds years of delay. Therefore I wouldn't even try adding this (POST /collections/{collectionId}/items for filtering nor POST /collections/{collectionId}/search) to Part 3. Adding another extension if/when QUERY arrives shouldn't be too much work. And if we get tired of waiting for QUERY we can revisit the topic.

[kalxas]

I am in favor of using POST /collections/{collectionId}/search for posting CQL queries until QUERY /collections/{collectionId}/items is available

[cportele]

Just to clarify:

Support for search resources or support for POST is out-of-scope of Part 3 and will be added in an additional part.

See the discussion in issue #449 or the related proposal. There is also work ongoing in OGC Testbed 18.

Here is what we have in the group charter:

A new part "Queries" will specify the Query resource (path element ”search”) supporting GET and POST. The Query resource at path “/search” will support multi-collection queries, the Query resource at path “/collections/{collectionId}/search” will support queries on a single collection. Support for stored/persistent queries will be considered.

Once IETF adopts the QUERY method, we can and should discuss how to leverage that. Until then, implementations that need POST on items for an API can implement that (we did), but I don't think that we need to standardize it at this point. For most APIs GET will be sufficient.

[m-mohr]

What would you think is the best approach to search collections? POST /collections also seems overloaded?
I'm asking for a potential extended version of https://github.com/stac-api-extensions/collection-search/

[cportele]

@m-mohr

We just discussed this in the SWG meeting this week. See #805.

While implementations can accept POSTed queries on /collections/{collectionId}/items with non-feature-encoding media types, e.g., with media type application/x-www-form-urlencoded or a new media type for a JSON query expression, this is not something that we want to standardize. POST on this resource should primarily be for creating new features. The QUERY method could be an option in the future, but there does not seem to be much momentum to add this method to HTTP.

The consensus in the discussion was that if GET on /collections/{collectionId}/items is not sufficient, the Search extension should be used, which will support POST queries to an endpoint search as decided with STAC in March 2018 (to use search was actually a STAC preference).

For the Search extension there is a proposal that was the basis for work in OGC Testbed 18. The related Engineering Report is not yet published (no idea why it is taking so long), so for now the document is only available on the portal.

[m-mohr]

Thanks, but I was specifically looking for Collection Search (i.e. potentially at GET and POST /collections), not item search. I understand that you are referring to Item Search, right? We neither want to overload POST /search nor POST /collections, I assume? @cportele

[cportele]

Ah, ok I misunderstood, because this issue is about queries on items.

Queries / paging / mutations on /collections was discussed in a few places, but I don't remember anything about POST queries in this context.

In the work on the Search extension in Testbed 18 we went for the following approach ([example API definition]):

• POST on /search executes an ad-hoc query
• PUT on /search/{queryId} creates or replaces a stored query

We will see what approach we eventually will select, but in general, a similar approach could also be used for /collections, if POST queries are really necessary for Collections.