doc/api/methods/groups.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "groups"
   6 ...
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/groups@
  14
  15 Object type: @j7d0g@
  16
  17 Example UUID: @zzzzz-j7d0g-0123456789abcde@
  18
  19 h2. Resource
  20
  21 Groups provides a way to apply the same permissions to a set of Arvados objects.  See "permission model":{{site.baseurl}}/api/permission-model.html for details.
  22
  23 Each Group has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
  24
  25 table(table table-bordered table-condensed).
  26 |_. Attribute|_. Type|_. Description|_. Example|
  27 |name|string|||
  28 |group_class|string|Type of group. This does not affect behavior, but determines how the group is presented in the user interface. For example, @project@ indicates that the group should be displayed by Workbench and arv-mount as a project for organizing and naming objects.|@"project"@
  29 null|
  30 |description|text|||
  31 |properties|hash|User-defined metadata, may be used in queries using "subproperty filters":{{site.baseurl}}/api/methods.html#subpropertyfilters ||
  32 |writable_by|array|List of UUID strings identifying Users and other Groups that have write permission for this Group.  Only users who are allowed to administer the Group will receive a full list.  Other users will receive a partial list that includes the Group's owner_uuid and (if applicable) their own user UUID.||
  33 |trash_at|datetime|If @trash_at@ is non-null and in the past, this group and all objects directly or indirectly owned by the group will be hidden from API calls.  May be untrashed.||
  34 |delete_at|datetime|If @delete_at@ is non-null and in the past, the group and all objects directly or indirectly owned by the group may be permanently deleted.||
  35 |is_trashed|datetime|True if @trash_at@ is in the past, false if not.||
  36
  37 h2. Methods
  38
  39 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
  40
  41 Required arguments are displayed in %{background:#ccffcc}green%.
  42
  43 h3. contents
  44
  45 Retrieve a list of items owned by the group.
  46
  47 Arguments:
  48
  49 table(table table-bordered table-condensed).
  50 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  51 {background:#ccffcc}.|uuid|string|The UUID of the group in question.|path||
  52 |limit|integer (default 100)|Maximum number of items to return.|query||
  53 |order|array|Attributes to use as sort keys to determine the order resources are returned, each optionally followed by @asc@ or @desc@ to indicate ascending or descending order. Sort within a resource type by prefixing the attribute with the resource name and a period.|query|@["collections.modified_at desc"]@|
  54 |filters|array|Conditions for filtering items.|query|@[["uuid", "is_a", "arvados#job"]]@|
  55 |recursive|boolean (default false)|Include items owned by subprojects.|query|@true@|
  56 |exclude_home_project|boolean (default false)|Only return items which are visible to the user but not accessible within the user's home project.  Use this to get a list of items that are shared with the user.|query|@true@|
  57
  58 Note: Because adding access tokens to manifests can be computationally expensive, the @manifest_text@ field is not included in listed collections.  If you need it, request a "list of collections":{{site.baseurl}}/api/methods/collections.html with the filter @["owner_uuid", "=", GROUP_UUID]@, and @"manifest_text"@ listed in the select parameter.
  59
  60 Note: Use filters with the attribute format @<item type>.<field name>@ to filter items of a specific type. For example: @["pipeline_instances.state", "=", "Complete"]@ to filter @pipeline_instances@ where @state@ is @Complete@. All other types of items owned by this group will be unimpacted by this filter and will still be included.
  61
  62 h3. create
  63
  64 Create a new Group.
  65
  66 Arguments:
  67
  68 table(table table-bordered table-condensed).
  69 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  70 |group|object||query||
  71 |async|boolean (default false)|Defer the permissions graph update by a configured number of seconds. (By default, @async_permissions_update_interval@ is 60 seconds). On success, the response is 202 (Accepted).|query|@true@|
  72
  73 h3. delete
  74
  75 Put a Group in the trash.  This sets the @trash_at@ field to @now@ and @delete_at@ field to @now@ + token TTL.  A trashed group is invisible to most API calls unless the @include_trash@ parameter is true.  All objects directly or indirectly owned by the Group are considered trashed as well.
  76
  77 Arguments:
  78
  79 table(table table-bordered table-condensed).
  80 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  81 {background:#ccffcc}.|uuid|string|The UUID of the Group in question.|path||
  82
  83 h3. get
  84
  85 Gets a Group's metadata by UUID.
  86
  87 Arguments:
  88
  89 table(table table-bordered table-condensed).
  90 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  91 {background:#ccffcc}.|uuid|string|The UUID of the Group in question.|path||
  92
  93 h3. list
  94
  95 List groups.
  96
  97 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
  98
  99 h3. show
 100
 101 show groups
 102
 103 Arguments:
 104
 105 table(table table-bordered table-condensed).
 106 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 107 {background:#ccffcc}.|uuid|string||path||
 108
 109 h3. update
 110
 111 Update attributes of an existing Group.
 112
 113 Arguments:
 114
 115 table(table table-bordered table-condensed).
 116 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 117 {background:#ccffcc}.|uuid|string|The UUID of the Group in question.|path||
 118 |group|object||query||
 119 |async|boolean (default false)|Defer the permissions graph update by a configured number of seconds. (By default, @async_permissions_update_interval@ is 60 seconds). On success, the response is 202 (Accepted).|query|@true@|
 120
 121 h3. untrash
 122
 123 Remove a Group from the trash.  This sets the @trash_at@ and @delete_at@ fields to @null@.
 124
 125 Arguments:
 126
 127 table(table table-bordered table-condensed).
 128 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 129 {background:#ccffcc}.|uuid|string|The UUID of the Group to untrash.|path||
 130 |ensure_unique_name|boolean (default false)|Rename project uniquely if untrashing it would fail with a unique name conflict.|query||
 131
 132 h3. shared
 133
 134 This endpoint returns the toplevel set of groups to which access is granted through a chain of one or more permission links rather than through direct ownership by the current user account.  This is useful for clients which wish to browse the list of projects the user has permission to read which are not part of the "home" project tree.
 135
 136 When called with "include=owner_uuid" this also returns (in the "included" field) the objects that own those projects (users or non-project groups).
 137
 138 Specifically, the logic is:
 139
 140 <pre>
 141 select groups that are readable by current user AND
 142     (the owner_uuid is a user (but not the current user) OR
 143      the owner_uuid is not readable by the current user OR
 144      the owner_uuid is a group but group_class is not a project)
 145 </pre>
 146
 147 In addition to the "include" parameter this endpoint also supports the same parameters as the "list method.":{{site.baseurl}}/api/methods.html#index
 148
 149 table(table table-bordered table-condensed).
 150 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 151 |include|string|If provided with the value "owner_uuid", this will return owner objects in the "included" field of the response.|query|?include=owner_uuid|