Get rid of the response parameter from the request body
gfenoy opened this issue · comments
I would like to propose that we remove the response parameter from the request body and use the following Prefer header options in replacement (cf. RFC 7240):
return=minimalwould correspond to the current behavior when"response": "raw"is set in the request body,return=representationwould correspond to the current behavior when"response": "document"is set in the request body.
In addition to remove the last remaining parameter (except inputs and outputs) from the request body, it also offers the advantage for servers to expose clearly what it supports.
For instance, a server that supports only, with the current configuration, Prefer: respond-async + "response": "document", it would have the opportunity to add the following parameter to its API to clearly express that it does support only this combinaison of parameters for the execution.
"oas-header1": {
"required": true,
"in": "header",
"name": "Prefer",
"schema": {
"type": "string",
"enum": [
"return=minimal",
"return=representation",
"respond-async;return=representation"
]
}
}
On the other hand, servers that will decide to store multipart encoded responses can then add the following parameter to their API:
"oas-header1": {
"required": true,
"in": "header",
"name": "Prefer",
"schema": {
"type": "string",
"enum": [
"return=minimal",
"return=representation",
"respond-async;return=representation",
"respond-async;return=minimal"
]
}
}
Then, this parameter can be referenced from the execute endpoint definition(s) within the exposed OpenAPI.
A demo implementation of this proposal can be found here (examples has been updated to follow the new proposed syntaxe and, the UI has also been adapted to produce request including the Prefer header nut no response in the request body).
Also, by accepting this proposal we give the opportunity to share and re-use the requests between different servers, I mean, between servers that may or may not support a given combinaison of parameters.
@gfenoy Sharing requests between different servers in my opinion is super important for the R in FAIR.
(e.g. sharing the workflow producing a map, and facilitating replicating the science and/or re-using it in different location and/or context).
Note that the response is optional and defaults to raw, but that inconveniently forces a raw response to allow re-use of the request with a different server. This is why I was arguing for a query parameter for response. The return preference might work too, but I find minimal and representation somewhat confusing.
In Workflows, we also need something to return an OGC API collection as an alternative to immediate execution, so response=collection would make sense, and it would be great if requests can be shared with workfows or not. We wouldn't have a corresponding response value with the prefer header for collection (and dataset) though, would we?
I feel very strongly that execution request documents define the process / workflow and not HOW the request is made -- that allows it to be re-used with multiple servers!!
That is also a big goal of the Workflows extension and referencing collections instead of specific URLs, omitting Area/Scale of Interest, negotiating APIs and formats/encodings separately.
I should mention for consideration that this change is a breaking change, it is coming in very late (after the feature freeze for sure) AND the changes to the document to accommodate this request would be extensive. Just saying ...
@jerstlouis I'm still going to create a pull request because I agree with this change but it might be a BIG pain in the you know what! We will know by tomorrow! ;)
@pvretano I really love this proposal, but my only concern is not having a Prefer: return value for collection and dataset responses for Workflows.
@jerstlouis well, I'll do the PR anyway and the SWG can decide what to do about this more easily. As for the workflow specific values, RFC 7240 does include a registration procedure OR we can define a register values with the OGC NA. Would that be OK for you?
@pvretano I would have flipped the return meaning from @gfenoy 's proposal though, so that's why I'm a bit confused.
I would have thought minimal is document (which would often contain only references), and representation is the whole thing (raw with the actual single or multipart data).
If the Workflows specifications / OGC NA can define additional values then sure, that's great we could add collection and dataset values for return (otherwise a query parameter might be better).
Something to keep in mind, if we use Prefer header, now the server would be free to return raw or document regardless of what the Prefer header says?
@jerstlouis my reading of the RFC says that the server must respond with a "minimal" response BUT what constitutes a minimal response is up to the server. I guess this means that we can put a requirement in the specification that says a "minimal" response shall be raw/document depending on how we resolve your other question about whether minimal=raw or minimal=document. I'm agnostic about what the interpretation should be.
Actually, I've thought about this some more and I don't see what advantage this proposed change brings. For example, @gfenoy indicates that with this change, execute requests can be more easily reused between servers. I don't see this. Any implementation of OAPIP core MUST support response=document and response=raw and so I can easily pass (assuming both servers offer the same process) an execute request between any two OAPIP implementations. Furthermore, if we use the Prefer header approach we need to define a default for the situations where the Prefer header does not accompany a request and what should that default be? ... and we now force clients to be prepared to receive either document or raw responses (at the server's discretion) is the Prefer header is not specified. Comments?
Today we discussed and proposed:
- response=minimal -> document (most often practically used with reference, so the document would be small)
- response=representation -> raw (always containing all the data, so the response would be the full thing)
@pvretano @gfenoy
My preference actually would be for the header to override the body, since it is the request document that would likely be re-used and the header would provide a mechanism to override the request without modifying the document itself. Thoughts?
I find that return=minimal|representation is more confusing than explicit response=raw|document. I don't see the advantage of this modification considering all the breaking changes it introduces.
As pointed out by @jerstlouis, a server can ignore the preference defined by Prefer header and do something else.
I find this does not align well with having the server that only supports one response type to add :
{
"oas-header1": {
"required": true,
"in": "header",
"name": "Prefer"
}
}@fmigneault as the specs currently stand, all servers must support both raw and document
The proposal in #217 avoids the confusion and avoids the possibility that the server can still return something completely different if it does not follow the client's preference.
@gfenoy can this be closed?
@bpross-52n unfortunately, I think so.
So, I sadly close it.
As Churchill said "Success consists of going from failure to failure without loss of enthusiasm.".
As I didn't lost my enthusiasm yet, I decided to finally keep this issue open, this way we will see if any PR comes from @pvretano. Indeed, he made mention that he will make one available.
Also, I don't remember anyone totally against the idea during the SWG discussions but, complaints about the timing of this proposal which was very late. Maybe the SWG can discuss again about this during the next meeting.
So, it may be great to keep this open for discussion and new ideas rising.
@bpross-52n I do propose that if it cannot be done for the current 1.0-draft.6, we tag this issue as 1.1?
@jerstlouis well, I'll do the PR anyway and the SWG can decide what to do about this more easily. As for the workflow specific values, RFC 7240 does include a registration procedure OR we can define a register values with the OGC NA. Would that be OK for you?
In case it is of any help, I can make the required PR too.
Please let me know.
@jerstlouis @gfenoy I have a PR almost ready ... I'll push it to the repo once it is done.
@gfenoy @pvretano My only concern is the change of meaning of return=minimal vs. representation proposed in #217 (requesting 'references' rather than 'values', rather than 'document' vs 'raw' -- while the dedicated end-points for individual vs. all outputs and media type handle the document vs. raw distinction in that proposal).
So I don't know whether including this PR or not in 1.0 makes the transition easier from 1.0 to 1.1, if #217 is being considered for 1.1?
Personally, I wish all breaking changes would be avoided for future versions (i.e. no breaking "2.0" version for the next 20 years).
SWG meeting from 2024-03-18: This should be fixed in the draft version 1.1.