WD-DataLink-1.0

[Markus Demleitner]

Dear list,

The TL;DR: of the below is: Perhaps we should think again whether
DALI is pertinent for Datalink or whether it's just a little
auxillary protocol. If we choose to adopt the whole DALI regime, we
should very briefly point out the major effects in Datalink just to
make sure people are aware of them.

On Tue, Dec 10, 2013 at 11:08:38AM -0800, Patrick Dowler wrote:
> On 12/10/2013 05:21 AM, Markus Demleitner wrote:
> >Is Datalink a stand-alone service?
> >----------------------------------
> 
> The intent is that we are defining a single capability so it is OK to
> have a {links} resource as part of some other service. The language

That's great.  Just in case you've missed it, in the example
capability I've included there's some additional VOResource metadata
which I'd like to see in the example in the documentation that will,
after all, ahem, "inspire" many implementors.

For the kind of standard service we have here it may seem be terribly
useful, but declaring the input parameters and the content type of
the response will help some day.  That's true in particular if we're
talking about having RESPONSEFORMAT; MAXREC, UPLOAD, VERSION, and
their ilk in Datalink.

> >RESPONSEFORMAT?
> >---------------
> 
> DALI describes how to define compliant capabilities. All DALI
> capabilities support this param and need to specify the default

Well, DALI is talking about "DAL jobs" and "DAL services" and
requires RESPONSEFORMAT for those.  On /examples or the VOSI
endpoints, for example, it does not require RESPONSEFORMAT.  

If we decide Datalink is not a DAL service (but rather some support
protocol like VOSI), we could save the language necessary to talk
about the response format and its ramifications.

As a brief illustration why I'm not so fond of seeing this here: If
DALI is pertinent, a Datalink service must reply with either
content-type: text/xml or content-type: application/x-votable+xml
with the same (VOTable) content depending on what RESPONSEFORMAT
actually is.  And I've not started on what it should usefully do when
RESPONSEFORMAT=application/x-votable+xml;serialization=BINARY2...

It's a few short words in a spec leading to many questions and quite
a bit of code in a compliant service.  That would be worth it if
there'd be credible usecase, but I really cannot see them; in
particular:

> means any client can use any DataLink capability, but implementers
> can always have their own custom output formats (json) to support
> their own use cases (eg their own portal).

... which of course they'd still be free to do, using some custom
extension for which standardization really doesn't help anyone
(different endpoint, magic custom parameter, http accept headers,
cookies, the options are endless even without RESPONSEFORMAT).

> >The example resource above could then be:
> >
> >   <RESOURCE type="datalinkService">
> 
> Just a nitpick: the type="service" was not supposed to be an example;
> that was really defining a "type of resource" just like

Oops -- that was a leftover of a misguided experiment.  I was not
proposing to change the type="service".

> >contentLength
> >-------------
> >
> Does changign this to be an estimate and your request above to
> reconcile names with ObsCore also imply your would want to use the
> ad-hoc name from ObsCore (access_estsize, iirc)?

I'd be all for aligning ObsCore and datalink names and concepts, as a
matter of principle (for the name of the principle I'm offering the
choice between the terms "concept economy" or "lazyness", as you
prefer).

> >I'd appreciate some language on what a service should do without
> >REQUEST.  Since the parameter is kinda superfluous in datalink, it's
> >tempting to just work without it, but of course that's a liability as it
> >may hide client bugs.
> 
> As with RESPONSEFORMAT, the REQUEST parameter is there to facilitate
> implementers having alternate functions that can be triggered, so it

...and again, we could save the hassle by declaring datalink an
auxillary endpoint rather than a DAL service in the DALI sense.  

Really, after SSA getData is dead, I'm again not aware of anything
that actually uses the REQUEST parameter sensibly even in the "major"
DAL protocols.  I have even less expectation to see any good use in
Datalink.  Instead, we'll carry around a useless, constant parameter
that will either clutter our service interface declarations, VOSI or
otherwise, or need additional code to become filtered out.

Realizing I should have made these points during standardization of
DALI, I'll shut up after this rant, but it feels just wrong to have
to repeat REQUEST=getLinks in all my tests or fail a (hopefully
forthcoming) validator without conceivably ever causing an
interoperability problem, because everyone will just hardcode
REQUEST=getLinks in their clients and ask themselves what exactly we
(as the standard writers) were thinking.

If, on the other hand, we go ahead with REQUEST, please include
language like

  As required by DALI, a service MUST respond with an error if the
  REQUEST parameter is missing or the value is not recognized.

-- otherwise I predict many services will at first not do anything
with REQUEST (as is the case with many SSA implementations), and
clients will start skipping REQUEST, and only when things are rolled
out out clients encounter the odd standards-compliant service... you
get the idea.

Incidentally, if we declare datalink a "DAL service" in the sense of
DALI, we must also say a few words about VERSION ("reject anything
other than 1.0").

Which I think we shouldn't, Datalink is just much nicer as a
lightweight auxillary protocol just like examples, tables or
availablility.



Parthian shot: Has anyone started to collect items to test for in a
datalink validator?


Cheers,

       Markus