[arvados-dev] API for addressing links

[Tom Clegg]

On Fri, Jan 10, 2014 at 11:29 AM, Tim Pierce <twp at curoverse.com> wrote:
> Currently /links/search, /links/delete and /links/show require a single
> "uuid" argument. Would it make sense to extend these to accept a "where"
> argument as well?

Sounds good to me. (But "delete" is the only method that needs anything, right?)

If you want to do "links/show" but you don't know the UUID yet, you do
"links/index?where={...}"

If you want to do "links/destroy" but you don't know the UUID yet, you
do ______.

I like the idea of passing a "where" parameter to "links/destroy", and
a sanity check like "cancel+fail if this matches more than N items".
N=1, unless specified by client.

Questions:

* Should the client be able to specify N for "fail if more than N items match"?
* Should the client be able to specify N for "delete first N if more
than N items match"?
* What should the request look like? "DELETE
/arvados/v1/links?where={...}", presumably?

Asides:

* Should we standardize on the method names as given in the discovery
doc, when discussing API methods? "arvados.links.show", etc. (I'm sure
I've used various conventions in git commit messages, with no apparent
rhyme or reason: links#show, links/show, ...)

* One REST pattern out there is to support multiple-item deletion with
"create collection" followed by "delete collection". This conflicts
with our use of the word "Collection". Aside from that, should we want
that, rather than permit >1 item to be deleted in a single API call?
The two-step approach mostly seems like unnecessary fuss to me: if you
want to know what you're deleting, you can always *choose* two-step,
even if the one-step option is available.