[p3t] Simple Cone Search starting point added

[Russ Allbery]

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://www.eyrie.org/~eagle/>