8 Copyright (C) The Arvados Authors. All rights reserved.
10 SPDX-License-Identifier: CC-BY-SA-3.0
13 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/groups@
17 Example UUID: @zzzzz-j7d0g-0123456789abcde@
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.
23 Each Group has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
25 table(table table-bordered table-condensed).
26 |_. Attribute|_. Type|_. Description|_. Example|
28 |group_class|string|Type of group. @project@ and @filter@ indicate that the group should be displayed by Workbench and arv-mount as a project for organizing and naming objects. @role@ is used as part of the "permission system":{{site.baseurl}}/api/permission-model.html. |@"filter"@
32 |properties|hash|User-defined metadata, may be used in queries using "subproperty filters":{{site.baseurl}}/api/methods.html#subpropertyfilters ||
33 |writable_by|array|(Deprecated) List of UUID strings identifying Users and other Groups that have write permission for this Group. Users who are allowed to administer the Group will receive a list of user/group UUIDs that have permission via explicit permission links; permissions via parent/ancestor groups are not taken into account. Other users will receive a partial list including only the Group's owner_uuid and (if applicable) their own user UUID.||
34 |can_write|boolean|True if the current user has write permission on this group.||
35 |can_manage|boolean|True if the current user has manage permission on this group.||
36 |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.||
37 |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.||
38 |is_trashed|datetime|True if @trash_at@ is in the past, false if not.||
39 |frozen_by_uuid|string|For a frozen project, indicates the user who froze the project; null in all other cases. When a project is frozen, no further changes can be made to the project or its contents, even by admins. Attempting to add new items or modify, rename, move, trash, or delete the project or its contents, including any subprojects, will return an error.||
41 h3(#frozen). Frozen projects
43 A user with @manage@ permission can set the @frozen_by_uuid@ attribute of a @project@ group to their own user UUID. Once this is done, no further changes can be made to the project or its contents, including subprojects.
45 The @frozen_by_uuid@ attribute can be cleared by an admin user. It can also be cleared by a user with @manage@ permission, unless the @API.UnfreezeProjectRequiresAdmin@ configuration setting is active.
47 The optional @API.FreezeProjectRequiresDescription@ and @API.FreezeProjectRequiresProperties@ configuration settings can be used to prevent users from freezing projects that have empty @description@ and/or specified @properties@ entries.
51 @filter@ groups are virtual groups; they can not own other objects. Filter groups have a special @properties@ field named @filters@, which must be an array of filter conditions. See "list method filters":{{site.baseurl}}/api/methods.html#filters for details on the syntax of valid filters, but keep in mind that the attributes must include the object type (@collections@, @container_requests@, @groups@, @workflows@), separated with a dot from the field to be filtered on.
53 Filters are applied with an implied *and* between them, but each filter only applies to the object type specified. The results are subject to the usual access controls - they are a subset of all objects the user can see. Here is an example:
67 This @filter@ group will return all groups (projects) that have a name starting with the word @Public@ and are visible to the user issuing the query. Because groups can contain many types of object, it will also return all objects of other types that the user can see.
69 The 'is_a' filter operator is of particular interest to limit the @filter@ group 'content' to the desired object(s). When the 'is_a' operator is used, the attribute must be 'uuid'. The operand may be a string or an array which means objects of either type will match the filter. This example will return all groups (projects) that have a name starting with the word @Public@, as well as all collections that are in the project with uuid @zzzzz-j7d0g-0123456789abcde@.
80 "collections.owner_uuid",
82 "zzzzz-j7d0g-0123456789abcde"
98 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
100 Required arguments are displayed in %{background:#ccffcc}green%.
102 h3(#contents). contents
104 Retrieve a list of items owned by the group or user. Use "recursive" to list objects within subprojects as well.
108 table(table table-bordered table-condensed).
109 |_. Argument |_. Type |_. Description |_. Location |_. Example |
110 {background:#ccffcc}.|uuid|string|The UUID of the group or user to enumerate. If this is a user UUID, this method returns the contents of that user's home project.|path||
111 |limit|integer (default 100)|Maximum number of items to return.|query||
112 |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"]@|
113 |filters|array|Conditions for filtering items.|query|@[["uuid", "is_a", "arvados#job"]]@|
114 |recursive|boolean (default false)|Include items owned by subprojects.|query|@true@|
115 |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. Uses the logic described under the "shared" endpoint.|query|@true@|
116 |include|string|If provided with the value "owner_uuid", this will return owner objects in the "included" field of the response.|query||
117 |include_trash|boolean (default false)|Include trashed objects.|query|@true@|
118 |include_old_versions|boolean (default false)|Include past versions of the collections being listed.|query|@true@|
119 |select|array|Attributes of each object to return in the response. Specify an unqualified name like @uuid@ to select that attribute on all object types, or a qualified name like @collections.name@ to select that attribute on objects of the specified type. By default, all available attributes are returned, except on collections, where @manifest_text@ is not returned and cannot be selected due to an implementation limitation. This limitation may be removed in the future.|query|@["uuid", "collections.name"]@|
123 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.
125 Use filters with the attribute format @<item type>.<field name>@ to filter items of a specific type. For example: @["container_requests.state", "=", "Final"]@ to filter @container_requests@ where @state@ is @Final@. All other types of items owned by this group will be unimpacted by this filter and will still be included.
127 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@. This can be used to fetch an object and its parent with a single API call.
136 table(table table-bordered table-condensed).
137 |_. Argument |_. Type |_. Description |_. Location |_. Example |
138 |group|object||query||
139 |async|boolean (default false)|Defer the permissions graph update by a configured number of seconds. (By default, @async_permissions_update_interval@ is 20 seconds). On success, the response is 202 (Accepted).|query|@true@|
143 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.
147 table(table table-bordered table-condensed).
148 |_. Argument |_. Type |_. Description |_. Location |_. Example |
149 {background:#ccffcc}.|uuid|string|The UUID of the Group in question.|path||
153 Gets a Group's metadata by UUID.
157 table(table table-bordered table-condensed).
158 |_. Argument |_. Type |_. Description |_. Location |_. Example |
159 {background:#ccffcc}.|uuid|string|The UUID of the Group in question.|path||
165 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
173 table(table table-bordered table-condensed).
174 |_. Argument |_. Type |_. Description |_. Location |_. Example |
175 {background:#ccffcc}.|uuid|string||path||
179 Update attributes of an existing Group.
183 table(table table-bordered table-condensed).
184 |_. Argument |_. Type |_. Description |_. Location |_. Example |
185 {background:#ccffcc}.|uuid|string|The UUID of the Group in question.|path||
186 |group|object||query||
187 |async|boolean (default false)|Defer the permissions graph update by a configured number of seconds. (By default, @async_permissions_update_interval@ is 20 seconds). On success, the response is 202 (Accepted).|query|@true@|
191 Remove a Group from the trash. This sets the @trash_at@ and @delete_at@ fields to @null@.
195 table(table table-bordered table-condensed).
196 |_. Argument |_. Type |_. Description |_. Location |_. Example |
197 {background:#ccffcc}.|uuid|string|The UUID of the Group to untrash.|path||
198 |ensure_unique_name|boolean (default false)|Rename project uniquely if untrashing it would fail with a unique name conflict.|query||
202 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. Similar behavior is also available with the @exclude_home_project@ option of the "contents" endpoint.
204 Specifically, the logic is:
207 select groups that are readable by current user AND
208 (the owner_uuid is a user (but not the current user) OR
209 the owner_uuid is not readable by the current user OR
210 the owner_uuid is a group but group_class is not a project)
213 table(table table-bordered table-condensed).
214 |_. Argument |_. Type |_. Description |_. Location |_. Example |
215 |include|string|If provided with the value "owner_uuid", this will return owner objects in the @included@ field of the response.|query||
219 When called with “include=owner_uuid”, the @included@ field of the response is populated with users and non-project groups that own the objects returned in @items@.
221 In addition to the "include" parameter this endpoint also supports the same parameters as the "list method.":{{site.baseurl}}/api/methods.html#index
projects / arvados.git / blob