Arvados

The include parameter is handled but isn't published by the discovery doc, so it doesn't appear in the API. This needs to be added to _contents_requires_parameters.

The "contents" endpoint can handle the case of no topmost group except that also isn't accepted by the API. (Seems like this is intended to work but "arv group contents" returns "Path not found" so it needs some tweaking).

So the thing I'm supposed to document can't actually be used, and the "include" option is mostly useless when you already know what the parent object is.

So the story needs to either be ditched or expanded to include tweaking the API server to actually accept these requests.

Peter Amstutz wrote:

The include parameter is handled but isn't published by the discovery doc, so it doesn't appear in the API. This needs to be added to _contents_requires_parameters.

The "contents" endpoint can handle the case of no topmost group except that also isn't accepted by the API. (Seems like this is intended to work but "arv group contents" returns "Path not found" so it needs some tweaking).

Auto-generated client libraries (python, ruby) can't use it, but Javascript/curl can, right?

the "include" option is mostly useless when you already know what the parent object is.

I think the idea here is to call .../contents?recursive=1&include=owner_uuid and get enough information to show the name (not just UUID) of the parent project of each returned item, without doing any additional API calls.

So the story needs to either be ditched or expanded to include tweaking the API server to actually accept these requests.

The way this is done for "shared" looks pretty easy, so expanding this to "document ... in the docs and the discovery doc" seems reasonable.

  def self._shared_requires_parameters
    rp = self._index_requires_parameters
    rp[:include] = { type: 'string', required: false }
    rp
  end

15421-include-param-doc @ 322b628a69e03d96dbf37fa33a402078af210b84

Peter Amstutz wrote:

15421-include-param-doc @ 322b628a69e03d96dbf37fa33a402078af210b84

I generally try and reduce parentheticals, would this work better?

When called with “include=owner_uuid” the @included@ field of the response is populated with users, projects, or other groups that own the objects returned in items.

The examples for include in both the content and shared sections show a URL query, but this doesn't seem consistent with examples in the rest of the API docs. No example is probably less confusing. If you think it needs an example, consider a full arv group command in the explanation paragraph.

Also, this might be more clear for the shared section:

When called with “include=owner_uuid” the @included@ field is populated with the users and non-project groups that own those projects.

Eric Biagiotti wrote:

Peter Amstutz wrote:

15421-include-param-doc @ 322b628a69e03d96dbf37fa33a402078af210b84

I generally try and reduce parentheticals, would this work better?
[...]I also think it would work better as a note under the table, so I have the chance review the table before an argument is explained in more detail.

Done.

The examples for include in both the content and shared sections show a URL query, but this doesn't seem consistent with examples in the rest of the API docs. No example is probably less confusing. If you think it needs an example, consider a full arv group command in the explanation paragraph.

Yea I think the example column is redundant here. Removed.

Also, this might be more clear for the shared section:
[...]

Done

Now f73fdac62e1b4a46858a67b57286765a652b565d

This LGTM. Thanks!