title: "links"
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/links@
-UUID type: @o0j2j@
+Object type: @o0j2j@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-o0j2j-0123456789abcde@
h2. Resource
-Each link has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Links are an extensible way to describe relationships between Arvados objects and metadata about individual objects.
+
+Each link has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|
-|tail_uuid|string|Object UUID at the tail (start, source, origin) of this link|
-|link_class|string|Class (see below)|
-|name|string|Link type (see below)|
-|head_uuid|string|Object UUID at the head (end, destination, target) of this link|
-|properties|hash|Additional information, expressed as a key→value hash. Key: string. Value: string, number, array, or hash.|
+|head_uuid|string|The object being described or acted on.|
+|tail_uuid|string|The origin or actor in the description or action (may be null).|
+|link_class|string|Type of link|
+|name|string|Primary value of the link.|
+|properties|hash|Additional information, expressed as a key→value hash. Key: string. Value: string, number, array, or hash. May be used in queries using "subproperty filters":{{site.baseurl}}/api/methods.html#subpropertyfilters|
h2. Link classes
Some classes are pre-defined by convention and have standard meanings attached to names.
-h3. provenance
+h3. permission
-table(table table-bordered table-condensed).
-|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|→Collection |provided → _collection uuid_
-{url→http://example.com/foo.tgz, retrieved_at→1352616640.000}||
-|Job→Collection |provided → _collection uuid_||
-|Specimen→Collection|provided → _collection uuid_||
-|Human→Specimen |provided → _specimen uuid_||
-|Human→Collection |provided → _collection uuid_||
+See "permission links":{{site.baseurl}}/api/permission-model.html#links section of the permission model.
-h3. permission
+h3. star
-table(table table-bordered table-condensed).
-|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|User→Group |{white-space:nowrap}. can_manage → _group uuid_|The User can read, write, and control permissions on the Group itself, every object owned by the Group, and every object on which the Group has _can_manage_ permission.|
-|User→Group |can_read → _group uuid_ |The User can retrieve the Group itself and every object that is readable by the Group.|
-|User→Job|can_write → _job uuid_ |The User can read and update the Job. (This works for all objects, not just jobs.)|
-|User→Job|can_manage → _job uuid_ |The User can read, update, and change permissions for the Job. (This works for all objects, not just jobs.)|
-|Group→Job|can_manage → _job uuid_ |Anyone with _can_manage_ permission on the Group can also read, update, and change permissions for the Job. Anyone with _can_read_ permission on the Group can read the Job. (This works for all objects, not just jobs.)|
+A **star** link is a shortcut to a project that is displayed in the user interface (Workbench) as "favorites". Users can mark their own favorites (implemented by creating or deleting **star** links).
+
+An admin can also create **star** links owned by the "Public favorites" project. These are favorites will be displayed to all users that have permission to read the project that has been favorited.
-h3. resources
+The schema for a star link is:
table(table table-bordered table-condensed).
-|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|User→Collection|wants → _collection uuid_ |Determines whether data can be deleted|
-|User→Job |wants → _job uuid_ |Determines whether a job can be cancelled|
+|_. Field|_. Value|_. Description|
+|owner_uuid|user or group uuid|Either the user that owns the favorite, or the "Public favorites" group.|
+|tail_uuid|user or group uuid|Should be the same as owner_uuid|
+|head_uuid|project uuid|The project being favorited|
+|link_class|string of value "star"|Indicates this represents a link to a user favorite|
+
+h4. Creating a public favorite
+
+@owner_uuid@ is either an individual user, or the "Public favorites" group. The @head_uuid@ is the project being favorited.
+
+<pre>
+$ linkuuid=$(arv --format=uuid link create --link '{
+ "link_class": "star",
+ "owner_uuid": "zzzzz-j7d0g-publicfavorites",
+ "tail_uuid": "zzzzz-j7d0g-publicfavorites",
+ "head_uuid": "zzzzz-j7d0g-theprojectuuid"}')
+</pre>
+
+h4. Removing a favorite
+
+<pre>
+$ arv link delete --uuid zzzzz-o0j2j-thestarlinkuuid
+</pre>
+
+h4. Listing favorites
+
+To list all 'star' links that will be displayed for a user:
+
+<pre>
+$ arv link list --filters '[
+ ["link_class", "=", "star"],
+ ["tail_uuid", "in", ["zzzzz-j7d0g-publicfavorites", "zzzzz-tpzed-currentuseruuid"]]]'
+</pre>
h3. tag
-A **tag** link describes an object using an unparsed plain text string. Tags can be used to annotate objects that are not editable, like collections and objects shared as read-only.
+A **tag** link describes an object using an unparsed plain text string. Tags can be used to annotate objects that are not directly editable by the user, like collections and objects shared as read-only.
table(table table-bordered table-condensed).
|_. tail_type→head_type|_. name→head_uuid {properties}|
|→Collection | _tag name_ → _collection uuid_|
|→Job | _tag name_ → _job uuid_|
-h3. human_trait
-
-table(table table-bordered table-condensed).
-|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|Human→Trait |measured → _trait uuid_ {value→1.83, unit→metre, measured_at→1352616640.000}||
-
-h3. identifier
-
-table(table table-bordered table-condensed).
-|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|→Human |hu123456 → _human uuid_||
+h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
-h2. Methods
+Required arguments are displayed in %{background:#ccffcc}green%.
h3. create
List links.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of links to return.|query||
-|order|string|Order in which to return matching links.|query||
-|filters|array|Conditions for filtering links.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
-h3. render_not_found
+h3. update
-render_not_found links
+Update attributes of an existing Link.
Arguments:
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|a|string||path||
+{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
+|link|object||query||
-h3. update
+h3. get_permissions
-Update attributes of an existing Link.
+Get all permission links that point directly to given UUID (in the head_uuid field). The requesting user must have @can_manage@ permission or be an admin.
Arguments:
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
-|link|object||query||
+{background:#ccffcc}.|uuid|string|The UUID of the object.|path||
projects / arvados.git / blobdiff