title: "links"
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/links@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Object type: @o0j2j@
+Example UUID: @zzzzz-o0j2j-0123456789abcde@
-h2. create
+h2. Resource
-Create a new Link.
+Links are an extensible way to describe relationships between Arvados objects and metadata about individual objects.
-Arguments:
+Each link has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|link|object||query||
+|_. Attribute|_. Type|_. Description|
+|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. delete
+h2. Link classes
-Delete an existing Link.
+Some classes are pre-defined by convention and have standard meanings attached to names.
-Arguments:
+h3. permission
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
+The significance of permission links is discussed in the "permission links":{{site.baseurl}}/api/permission-model.html#links section of the permission model documentation.
-h2. destroy
+h3. star
-destroy links
+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).
-Arguments:
+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.
+
+The schema for a star link is:
table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|uuid|string||path||
+|_. 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|
-h2. get
+h4. Creating a public favorite
-Gets a Link's metadata by UUID.
+@owner_uuid@ is either an individual user, or the "Public favorites" group. The @head_uuid@ is the project being favorited.
-Arguments:
+<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>
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
+h4. Removing a favorite
-h2. index
+<pre>
+$ arv link delete --uuid zzzzz-o0j2j-thestarlinkuuid
+</pre>
-index links
+h4. Listing favorites
-Arguments:
+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 directly editable by the user, like collections and objects shared as read-only.
table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|tail_uuid|string||path||
-|order|string||query||
-|where|object||query||
+|_. tail_type→head_type|_. name→head_uuid {properties}|
+|→Collection | _tag name_ → _collection uuid_|
+|→Job | _tag name_ → _job uuid_|
-h2. list
+h2. Methods
-List links.
+See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
+h3. create
+
+Create a new Link.
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||
-|pageToken|string|Page token.|query||
-|q|string|Query string for searching links.|query||
-|where|object|Conditions for filtering links.|query||
+|link|object||query||
-h2. render_not_found
+When you create a new permission link with the same @head_uuid@ and @tail_uuid@ as an existing permission link, the API returns the existing link instead of creating a new one. If the requested permission level is higher than the existing link, the existing link is updated accordingly. Otherwise the existing link is returned unchanged.
-render_not_found links
+h3. delete
+
+Delete 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||
-h2. show
+When you delete a permission link, any other existing permission links that have the same @head_uuid@ and @tail_uuid@ are also deleted.
-show links
+h3. get
+
+Gets a Link's metadata by UUID.
Arguments:
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|uuid|string||path||
+{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
-h2. update
+h3. list
+
+List links.
+
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
+
+h3. update
Update attributes of an existing Link.
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
|link|object||query||
+
+When you update a permission link such that it has the same @head_uuid@ and @tail_uuid@ as one or more existing permission links, the API deletes the other links. If the highest permission level among the deleted links was higher than the newly updated link, the updated link's permission level is increased accordingly.
+
+h3. get_permissions
+
+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 object.|path||
projects / arvados.git / blobdiff