Project

General

Profile

Actions

Bug #15421

closed

Document include parameter for the group contents API

Added by Tom Morris about 3 years ago. Updated over 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 1 (0 open1 closed)

Task #15438: Review 15421-include-param-docResolvedEric Biagiotti07/09/2019

Actions
Actions #1

Updated by Tom Morris about 3 years ago

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

Updated by Peter Amstutz about 3 years ago

  • Assigned To set to Peter Amstutz
Actions #3

Updated by Peter Amstutz about 3 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.

Actions #4

Updated by Tom Clegg about 3 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
Actions #5

Updated by Peter Amstutz about 3 years ago

Actions #6

Updated by Eric Biagiotti about 3 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.

Actions #7

Updated by Peter Amstutz about 3 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

Actions #8

Updated by Eric Biagiotti about 3 years ago

This LGTM. Thanks!

Actions #9

Updated by Peter Amstutz about 3 years ago

  • Status changed from New to Resolved
Actions #10

Updated by Peter Amstutz over 2 years ago

  • Release set to 22
Actions

Also available in: Atom PDF