Bug #15421

Document include parameter for the group contents API

Added by Tom Morris over 2 years ago. Updated almost 2 years ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
-
Target version:
Start date:
07/09/2019
Due date:
% Done:

100%

Estimated time:
(Total: 0.00 h)
Story points:
-
Release relationship:
Auto

Description

It's currently only documented for the shared groups, but supported for all group contents


Subtasks

Task #15438: Review 15421-include-param-docResolvedEric Biagiotti

Associated revisions

Revision e843017b
Added by Peter Amstutz over 2 years ago

Merge branch '15421-include-param-doc' closes #15421

Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <>

History

#1 Updated by Tom Morris over 2 years ago

  • Target version changed from 2019-07-03 Sprint to 2019-07-17 Sprint

#2 Updated by Peter Amstutz over 2 years ago

  • Assigned To set to Peter Amstutz

#3 Updated by Peter Amstutz over 2 years ago

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.

#4 Updated by Tom Clegg over 2 years ago

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

#5 Updated by Peter Amstutz over 2 years ago

#6 Updated by Eric Biagiotti over 2 years ago

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.
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.

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.

#7 Updated by Peter Amstutz over 2 years ago

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

#8 Updated by Eric Biagiotti over 2 years ago

This LGTM. Thanks!

#9 Updated by Peter Amstutz over 2 years ago

  • Status changed from New to Resolved

#10 Updated by Peter Amstutz almost 2 years ago

  • Release set to 22

Also available in: Atom PDF