<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Aptos;
panose-1:2 11 0 4 2 2 2 2 2 4;}
@font-face
{font-family:Consolas;
panose-1:2 11 6 9 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0cm;
font-size:12.0pt;
font-family:"Aptos",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
pre
{mso-style-priority:99;
mso-style-link:"HTML Preformatted Char";
margin:0cm;
margin-bottom:.0001pt;
font-size:10.0pt;
font-family:"Courier New";}
span.HTMLPreformattedChar
{mso-style-name:"HTML Preformatted Char";
mso-style-priority:99;
mso-style-link:"HTML Preformatted";
font-family:Consolas;}
span.EmailStyle20
{mso-style-type:personal-reply;
font-family:"Aptos",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;
mso-ligatures:none;}
@page WordSection1
{size:612.0pt 792.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body lang="EN-GB" link="blue" vlink="purple" style="word-wrap:break-word">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US">Hi,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US">My main point was that the POST was not really following the REST pattern –
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><a href="https://restfulapi.net/rest-put-vs-post/">https://restfulapi.net/rest-put-vs-post/</a> is that the main distinction between POST and PUT is the POST is not expected to be
idempotent.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US">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.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US">Cheers,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"> Paul.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<div id="mail-editor-reference-message-container">
<div>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal" style="mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:12.0pt;margin-left:36.0pt">
<b><span style="color:black">From: </span></b><span style="color:black">Russ Allbery <eagle@eyrie.org><br>
<b>Date: </b>Friday, 23 February 2024 at 19:54<br>
<b>To: </b>Paul Harrison <paul.harrison@manchester.ac.uk><br>
<b>Cc: </b>P3t@ivoa.net <P3t@ivoa.net><br>
<b>Subject: </b>Re: [p3t] Simple Cone Search starting point added<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:36.0pt;mso-line-height-alt:.75pt"><span style="font-size:1.0pt;color:white">Paul Harrison <paul.</span><span style="font-size:1.0pt;font-family:"Arial",sans-serif;color:white"> </span><span style="font-size:1.0pt;color:white">harrison@</span><span style="font-size:1.0pt;font-family:"Arial",sans-serif;color:white"> </span><span style="font-size:1.0pt;color:white">manchester.</span><span style="font-size:1.0pt;font-family:"Arial",sans-serif;color:white"> </span><span style="font-size:1.0pt;color:white">ac.</span><span style="font-size:1.0pt;font-family:"Arial",sans-serif;color:white"> </span><span style="font-size:1.0pt;color:white">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?
<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:36.0pt;mso-line-height-alt:.75pt"><span style="font-size:1.0pt;color:white">ZjQcmQRYFpfptBannerStart<o:p></o:p></span></p>
</div>
<div style="border:none;border-top:solid #90A4AE 3.0pt;padding:0cm 0cm 0cm 0cm;display:block!important;text-align:left!important;margin:0px!important;padding:16px!important;border-radius:4px!important;min-width:200px!important;background-color:#D0D8DC!important;border-top:#90a4ae!important" id="pfptBanner6r7i1cu">
<div id="pfptBanner6r7i1cu">
<div id="pfptBanner6r7i1cu">
<p class="MsoNormal" style="margin-left:36.0pt;line-height:13.5pt;background:#D0D8DC">
<b><span lang="EN" style="font-family:"Arial",sans-serif;color:black">This Message Is From a New External Sender
<o:p></o:p></span></b></p>
</div>
<div id="pfptBanner6r7i1cu">
<p class="MsoNormal" style="margin-left:36.0pt;line-height:13.5pt;background:#D0D8DC">
<span lang="EN" style="font-family:"Arial",sans-serif;color:black">You have not previously corresponded with this sender. Please exercise caution when opening links or attachments included in this message.
<o:p></o:p></span></p>
</div>
</div>
<div>
<p class="MsoNormal" style="margin-left:36.0pt;background:#D0D8DC"><span lang="EN" style="color:black"> </span><span lang="EN"><o:p></o:p></span></p>
</div>
</div>
<div>
<p class="MsoNormal" style="margin-left:36.0pt;mso-line-height-alt:.75pt"><span style="font-size:1.0pt;color:white">ZjQcmQRYFpfptBannerEnd<o:p></o:p></span></p>
</div>
<pre style="margin-left:36.0pt;white-space:pre-wrap"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">Paul Harrison <paul.harrison@manchester.ac.uk> writes:<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">> * It looks a bit unRESTful to POST to the /jobs/{job_id}/start do we<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">> want non-idempotent behaviour there - is that supposed to be starting a<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">> new job with the same parameters?<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">No, this is a replacement for the current UWS POST to /jobs/{job_id}/phase<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">with body phase=RUN.<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">This is kind of a subtle point, and maybe (probably!) I'm picking nits,<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">but my argument here is that the semantics of the current UWS API is<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">subtlely incorrect in a couple of ways. One is that it's apparently<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">setting the phase to something that isn't a valid value for that attribute<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">of the job ("RUN"). The other is that the user can't actually set the<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">phase because the phase should reflect the underlying state of the job and<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">should only be set by the job system. Instead, the user is issuing a<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">command that, if successful, means the job will start running, which will<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">cause various other things to happen to the job record including its phase<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">changing to EXECUTING.<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">In other words, I don't think this is best thought of as a state change on<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">the stored data for the job. I think it's instead an action verb on a job<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">that was created PENDING for some reason (possibly because the user wanted<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">to get an estimate first before starting it, for example). That action,<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">if successful, will result in state changes, but the state changes are<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">better thought of as a side effect of the real intended action, namely<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">starting the job execution.<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">There isn't a consensus on how to represent action verbs on an existing<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">resource in REST, but POST to a command URL below the resource is one<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">fairly common pattern. The body is irrelevant in this case since no<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">user-supplied data is needed, but to avoid XSS issues the body should have<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">some JSON content.<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">This could be confusing in a world where many of the attributes of the job<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">are treated as subresource of the job, since then there's namespace<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">collision between attributes and action verbs, but this proposal also<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">argues for not treating job attributes as resources. The full job record<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">is pretty tiny, so there doesn't seem to be much to be gained in<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">efficiency by being able to request only specific attributes, and PATCH is<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">available as a REST verb to modify job attributes. That avoids a few<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">other issues, such as how to represent the body of GET requests for<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">attributes with no value since empty bodies should be avoided since it's<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">hard to distinguish them from truncated results.<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">> * If we are going to make some radical changes to UWS then it would be<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">> nice to return to the original concept (before the standardisation<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">> compromises) that UWS treated the body content of the job creation POST<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">> as an opaque blob – it could then be anything (including XML! or even<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">> some binary format)<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">One of the nice properties of having the job parameters for any UWS job be<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">a JSON model is that it means we can easily return the job parameters when<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">the UWS job record is retrieved, which in turn is very helpful for<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">debugging, status displays, job history, and other uses. If the UWS job<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">parameters are not in JSON, that either forces them into a separate API<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">call to return the opaque blob and some indication of what format that<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">blob is in, or it requires nested encodings in the response.<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">If we're anticipating UWS IVOA services where some job parameters are data<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">that is not JSON-encodable (if one of the parameters to the job is a FITS<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">file, for instance), we'll have to deal with this one way or another. But<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">even then, I'd rather deal with that similar to how job results are<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">handled: a JSON model that in that case contains pointers to additional<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">objects stored elsewhere. This seems like a better way of handling<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">possibly large data files. (If this came up, I would also probably argue<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">for treating job *parameters* as distinct from job *input data* because I<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">think it will result in a less ambiguous and easier-to-implement<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">representation of the job.)<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">Nesting multiple encodings in the same response is something I would like<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">to avoid if at all possible, since it adds significant implementation pain<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">that works contrary to a design goal of letting most of the work be done<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">automatically by web frameworks.<o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">-- <o:p></o:p></span></pre>
<pre style="margin-left:36.0pt"><span style="font-size:12.0pt;font-family:"Arial",sans-serif">Russ Allbery (eagle@eyrie.org) <<a href="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$</a>[eyrie[.]org]><o:p></o:p></span></pre>
</div>
</div>
</div>
</body>
</html>