KVP-encoding for EXECUTE request
pvretano opened this issue · comments
This issue is motivated by the current work being done in the TB16 Data Access and Process API thread and my desire to converge that work with what is being done in the OAPIP SWG.
Currently, the only way to execute a process is to POST and JSON-encoded execute request to a process' jobs endpoint. The purpose of this issue is to start thinking about what form a KVP-encoded execute request might take.
These are my opening musings ... comments welcome!
Execution endpoint
To be compatible with the current state of the OAPIP specification, the execute endpoint is /processes/{processId}/jobs.
I don't fundamentally have a problem using this endpoint but I think that /processes/{processId} is a more natural endpoint for invoking a process using GET. Of course, the current behaviour of doing a GET at the /processes/{processId} endpoint is to get a process description. In retrospect I would have advocated for a different endpoint for getting a process description (e.g. something like /processes/{processId}/api).
Basic form of the URL
The basic form of a URL that can be used to invoke a process is:
http://www.someserver.com/.../processes/{processId}/jobs?
mode=sync|async|auto&
response=raw|document&
{id}=<input value>&{id}=<input value>&...
output=<output reference>&output=<output reference>&...
Each of mode, response and output parameter can be prefixed by the string "oapip:" if it is necessary to discriminate the parameter from an input of the same name (e.g. oapip:mode as the mode parameter versus mode as the name of a process input).
Process Inputs (<input value>)
Each process input maps to a query parameter on the URL. The basic forms of process inputs as query parameters are:
COMPLEX (by value):
{inputId}=<value>[,<format facets>]
COMPLEX (be reference):
{inputId}=<uri>[,<format facets>]]
LITERAL:
{inputId}="string"[,<data type and uom facets>]
BBOX DATA:
{inputId}=1,2,3,4[[,5,6][,<crs ref>]]
GEOMETRY DATA:
{inputId}=<wkt string>[,<crs ref>]
{inputId} is the process input identifier.
<value> is the value of the input.
<uri> is a reference to a complex value.
"string" is a literal value.
<format facets> is a comma-separated triple of the form {mimeType}[,{schema}[,{encoding}]] where the commas are literal commas. Embedded commas must be appropriately encoded.
<data type and uom facets> is a comma-separated quad of the form {dataType}[,{dataTypeRef}[,{uom}[,{uomRef}]]] where the commas are literal commas and embedded commas must be appropriately encoded.
NOTE: Still need to think about how arrays of values are specified given that the input parameter is already an array to accommodate format facets and data type and uom facets. Perhaps the default behaviour should be that an array of values is interpreted as an array of values UNLESS format facets are specified in which case the array must be delimited by "[ ]" (i.e. input1=val,val,val,val versus input1=%5Bval%2Cval%2Cval%2Cval%5D,{mimeType},{schema},{encoding}).
<crs ref> is a reference to a coordinate reference system
A specific Input can be repeated as a query parameter (i.e. type=array and collectionFormat=multi in OpenAPI parlance) if the cardinality of the input is greater than one.
NOTE: See note above about arrays of values. This approach supports inputs with cardinality>1 but it is questionable whether this is the "most" natural way to handle this.
In its most basic form, however, it is important to note that a process input looks like any other query parameter on a URL (i.e. {inputId}=value).
Process outputs (<output reference>)
Each process output can be specified using the output query parameter. Multiple output parameters can be specified to request multiple outputs. The basic form of the output parameter is:
output={outputId}[,value|reference][,{mimeType}[,{schema}[,{encoding}]]]
NOTE: What is not yet supported: nested inputs.
PENDING: An OpenAPI example from the DAPA thread that show KVP process invocation.
Peter,
Great start.
We have a couple processes that could benefit from this kvp encoding.
https://labs.waterdata.usgs.gov/api/nldi/pygeoapi/processes?f=html
Anything I can do to help move this proposal along?
I believe method/endpoint GET /processes/{processId}/execution should be used instead of jobs to be consistent with the current execution endpoint for POST JSON.
Although job status /processes/{processId}/jobs was modified at some point to /jobs, the /processes/{processId}/jobs is still employed in our case. This GET KVP variant will be conflicting with it.
@fmigneault the proposal was written for the a year ago so it will definitely need some tweaking.
@dblodgett-usgs I have it on my todo list to write up the extension but no ETA as yet. Hopefully before the end of the year ... maybe some "fun" specification writing over the holidays! ;)
I also think that referencing to input / output ID must be improved.
Similarly to WPS-1/2, there should be a inputs=<input1-id>=<input1-value>;... definition.
Having the input IDs directly can cause conflict.
For example, mode is a very common process input, and there won't be any way to distinguish it from the execution's mode.
@fmigneault roger that.
Closed by #290