[pygeoapi] Process - how to request a job result with mimetype='multipart/related' ?

Tue Dec 19 05:46:50 PST 2023

Dear all,
thank you to Ricardo,
I elaborated his answer, but I am still confused.

As per § 6.1: "JSON is the encoding for request and responses."

As stated in requirement 17, response default to "raw", but also allows 
"document".

I understand that responses may accept a format parameter:
possible values are "json" (the default) and "html".

At this point I could guess "raw"<->"json", "document"<->"html".

The example next to requirement 43 is about a job result with no
format specific parameter, and it returns a response encoded JSON.

As far as I understand, for a job with:
-) execution: async
-) transmission mode: value
-) # outputs: *

the "body content" will be:
-) if the format is missing (i.e. "json") the returned value is encoded 
JSON (as per the above example)
-) if the format is "html" (i.e. "document") the returned value is 
encoded JSON (mimetype='application/json', as per tables 11 and 12)
[There is no example: should it be the same as before?]

**Question is**:
how is it specified that the response of the above example should be of 
type "raw" (mimetype='multipart/related')?

Thak you,
Francesco

On 06/12/23 18:32, Ricardo Filipe Soares Garcia da wrote:
> Hi Francesco
> 
> If I understand the question correctly, then I think table 12 of the OGC 
> API - Processes standard provides you with the answer. The way that 
> results are accessed depends on your original processing request:
> 
> 1. if you requested sync execution, results ought to be transmitted in a 
> similar way as the one described for async (more on that below)
> 2. if you requested async execution (or let's say you requested sync, 
> but want to retrieve the results again), then it depends on a number of 
> factors:
> 
> 2.1. If response type is 'raw' and transmission mode is 'value' and 
> there is a single output, then the result will be available at the link 
> indicated by the 'Location' header in the raw output type (e.g. a 
> geotiff file that was generated as the result of the process execution)
> 
> 2.2. If response type is 'raw' and transmission mode is 'value' and 
> there are a multiple outputs, then the result will be a 
> multipart/related response with each result being a 'part', and they 
> will be available at the link indicated by the 'Location' header (e.g. 
> multiple geotiffs generated, then response will have all of them 
> concatenated, each will be a 'part' of the message) - This is the same 
> way as an email client would transmit images via email. Browse the 
> Internet for information on the 'multipart/related' media type in order 
> to know more about this
> 
> 2.3. If response type is 'raw' and transmission mode is 'reference' and 
> there are is either a single output or multiple outputs, then when you 
> visit the resource that the 'Location' header links to you will get back 
> an empty response body, but the response headers shall contain a 'Link' 
> header for each output, with the value of the header being a link for 
> each output where you should be able to get each result in its raw 
> output type (i.e. there will be a 'Link' header with a link for the 
> actual geotiff generated as a process result)
> 
> 2.4. If response type is 'raw' and transmission mode is mixed (i.e. 
> there are multiple outputs and some of them are to be transmitted by 
> 'value' while others by 'reference') then the result will again be a 
> multipart/related resource and presumably there will be one 'part' for 
> each output that is being transmitted by 'value' and one 'Link' header 
> for each output being transmitted by 'reference' - I think this is my 
> interpretation of the standard, it does not actually say this though
> 
> 2.5. If the response type is 'document', the response will always be a 
> JSON document that complies with the relevant 'results.yaml' schema (as 
> mentioned in the standard).
> 
> 2.5.1 For each generated process result that has its transmission mode 
> requested as 'value', the actual result is transmitted in the JSON 
> document. If the result it is a JSON type (int, str, object, etc) then 
> it is shown directly. If the result is some binary data, then it should 
> be encoded as a string, maybe using base64, but there is a provision for 
> specifying the encoding of the data and also the media-type of 
> theunderlying data - you can check the example 2 provided in section 
> 7.13.2 of the standard for more info on this
> 
> 2.5.2. For each generated process result that has its transmission mode 
> set to 'reference' then the response JSON document will include a link 
> to the resource.
> 
> 
> I hope this makes it a bit clearer.
> 
> 
> Please note that, as mentioned in a previous message, pygeoapi does not 
> currently support this form of result retrieval, not yet anyway ;) - it 
> effectively ignores whatever form of output generation has been (thereby 
> always assuming response type 'raw' and transmission mode 'value').
> 
> As for where to post these kinds of questions, I'm not sure, but maybe 
> you can open an issue at the standard's github repo? Here:
> 
> https://github.com/opengeospatial/ogcapi-processes/issues 
> <https://github.com/opengeospatial/ogcapi-processes/issues>
> 
> I guess asking them here might also be appropriate.
> 
> 
> Best regards
> 
> 
> 
> Francesco Martinelli via pygeoapi <pygeoapi at lists.osgeo.org 
> <mailto:pygeoapi at lists.osgeo.org>> escreveu no dia quarta, 6/12/2023 
> à(s) 16:29:
> 
>     Hi there,
>     I am not sure this is the appropriate mailing list where to ask:
>     if this is inappropriate I apologize,
>     and if possible I ask to advise where should I post my question.
> 
>     Reading the OGC API - PROCESSES -Part 1: CORE
>     I don't find a way (if possible) to retrieve a single output result
>     from
>     a job.
>     Specifically I am looking to paragraph 7.13
> 
>     If I submit an execute request, and I get back a UUID for the job (i.e.
>     a 'Location' in the header, where the location contains the UUID/jobID),
>     then I can thereafter get the results of the job on the path
>     /jobs/{jobID}/results.
> 
>     However if I had multiple outputs (possibly of sensible size)
>     and I want to get only one,
>     I don't find a way to get only that single output: is it possible?
>     If positive: how to specify this request?
> 
> 
>     Thank you,
>     Francesco
>     _______________________________________________
>     pygeoapi mailing list
>     pygeoapi at lists.osgeo.org <mailto:pygeoapi at lists.osgeo.org>
>     https://lists.osgeo.org/mailman/listinfo/pygeoapi
>     <https://lists.osgeo.org/mailman/listinfo/pygeoapi>
> 
> 
> 
> -- 
> ___________________________ ___ __
> Ricardo Garcia Silva