[p3t] Simple Cone Search starting point added

[Paul Harrison]

Hi,

My main point was that the POST was not really following the REST pattern –
https://restfulapi.net/rest-put-vs-post/ is that the main distinction between POST and PUT is the POST is not expected to be idempotent.
As one of the complaints about the existing UWS REST API spec was the incorrect use of GET (which I agree is distasteful, but was driven by the requirement to be able to drive the interface from a browser without Javascript) then we should be careful about verb use in any revision.

Cheers,
                Paul.

From: Russ Allbery <eagle at eyrie.org>
Date: Friday, 23 February 2024 at 19:54
To: Paul Harrison <paul.harrison at manchester.ac.uk>
Cc: P3t at ivoa.net <P3t at ivoa.net>
Subject: Re: [p3t] Simple Cone Search starting point added
Paul Harrison <paul. harrison@ manchester. ac. uk> writes: > * It looks a bit unRESTful to POST to the /jobs/{job_id}/start do we > want non-idempotent behaviour there - is that supposed to be starting a > new job with the same parameters?
ZjQcmQRYFpfptBannerStart
This Message Is From a New External Sender
You have not previously corresponded with this sender. Please exercise caution when opening links or attachments included in this message.

ZjQcmQRYFpfptBannerEnd

Paul Harrison <paul.harrison at manchester.ac.uk> writes:



> * It looks a bit unRESTful to POST to the /jobs/{job_id}/start do we

> want non-idempotent behaviour there - is that supposed to be starting a

> new job with the same parameters?



No, this is a replacement for the current UWS POST to /jobs/{job_id}/phase

with body phase=RUN.



This is kind of a subtle point, and maybe (probably!) I'm picking nits,

but my argument here is that the semantics of the current UWS API is

subtlely incorrect in a couple of ways.  One is that it's apparently

setting the phase to something that isn't a valid value for that attribute

of the job ("RUN").  The other is that the user can't actually set the

phase because the phase should reflect the underlying state of the job and

should only be set by the job system.  Instead, the user is issuing a

command that, if successful, means the job will start running, which will

cause various other things to happen to the job record including its phase

changing to EXECUTING.



In other words, I don't think this is best thought of as a state change on

the stored data for the job.  I think it's instead an action verb on a job

that was created PENDING for some reason (possibly because the user wanted

to get an estimate first before starting it, for example).  That action,

if successful, will result in state changes, but the state changes are

better thought of as a side effect of the real intended action, namely

starting the job execution.



There isn't a consensus on how to represent action verbs on an existing

resource in REST, but POST to a command URL below the resource is one

fairly common pattern.  The body is irrelevant in this case since no

user-supplied data is needed, but to avoid XSS issues the body should have

some JSON content.



This could be confusing in a world where many of the attributes of the job

are treated as subresource of the job, since then there's namespace

collision between attributes and action verbs, but this proposal also

argues for not treating job attributes as resources.  The full job record

is pretty tiny, so there doesn't seem to be much to be gained in

efficiency by being able to request only specific attributes, and PATCH is

available as a REST verb to modify job attributes.  That avoids a few

other issues, such as how to represent the body of GET requests for

attributes with no value since empty bodies should be avoided since it's

hard to distinguish them from truncated results.



> * If we are going to make some radical changes to UWS then it would be

> nice to return to the original concept (before the standardisation

> compromises) that UWS treated the body content of the job creation POST

> as an opaque blob – it could then be anything (including XML! or even

> some binary format)



One of the nice properties of having the job parameters for any UWS job be

a JSON model is that it means we can easily return the job parameters when

the UWS job record is retrieved, which in turn is very helpful for

debugging, status displays, job history, and other uses.  If the UWS job

parameters are not in JSON, that either forces them into a separate API

call to return the opaque blob and some indication of what format that

blob is in, or it requires nested encodings in the response.



If we're anticipating UWS IVOA services where some job parameters are data

that is not JSON-encodable (if one of the parameters to the job is a FITS

file, for instance), we'll have to deal with this one way or another.  But

even then, I'd rather deal with that similar to how job results are

handled: a JSON model that in that case contains pointers to additional

objects stored elsewhere.  This seems like a better way of handling

possibly large data files.  (If this came up, I would also probably argue

for treating job *parameters* as distinct from job *input data* because I

think it will result in a less ambiguous and easier-to-implement

representation of the job.)



Nesting multiple encodings in the same response is something I would like

to avoid if at all possible, since it adds significant implementation pain

that works contrary to a design goal of letting most of the work be done

automatically by web frameworks.



--

Russ Allbery (eagle at eyrie.org)             <https://urldefense.com/v3/__https://www.eyrie.org/*eagle/__;fg!!PDiH4ENfjr2_Jw!ASH-Y6T8D4CfzUMRHIgrxkSIKNuuM8d23DUf_lHpucPYYhDRpnEJdTxehaTK64FkDRgsenr9DbG3e5ZJeuXZFEM$<https://urldefense.com/v3/__https:/www.eyrie.org/*eagle/__;fg!!PDiH4ENfjr2_Jw!ASH-Y6T8D4CfzUMRHIgrxkSIKNuuM8d23DUf_lHpucPYYhDRpnEJdTxehaTK64FkDRgsenr9DbG3e5ZJeuXZFEM$>[eyrie[.]org]>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ivoa.net/pipermail/p3t/attachments/20240229/1a006a48/attachment-0001.htm>