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@
+Object type: @o0j2j@
+
+Example UUID: @zzzzz-o0j2j-0123456789abcde@
+
+h2. Resource
+
+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|
+|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. permission
+
+See "permission links":{{site.baseurl}}/api/permission-model.html#links section of the permission model.
+
+h3. star
+
+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 system user, with @tail_uuid@ as the "All Users" group. These are "public favorites" that will be displayed to all users that have permission to read the project that has been favorited. Note: setting a public favorite also requires creating a @can_read@ permission link from @All Users@ to the 'star' link record.
+
+The schema for a star link is:
+
+table(table table-bordered table-condensed).
+|_. Field|_. Value|_. Description|
+|tail_uuid|user or group uuid|Either the user that owns the favorite, or the "All Users" group for public favorites.|
+|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
+
+@tail_uuid@ is either an individual user, or the "All Users" group. The @head_uuid@ is the project being favorited.
+
+<pre>
+$ linkuuid=$(arv --format=uuid link create --link '{
+ "link_class": "star",
+ "owner_uuid": "zzzzz-tpzed-000000000000000",
+ "tail_uuid": "zzzzz-j7d0g-fffffffffffffff",
+ "head_uuid": "zzzzz-j7d0g-theprojectuuid"}')
+
+$ arv link create --link '{
+ "link_class": "permission",
+ "name": "can_read",
+ "tail_uuid": "zzzzz-j7d0g-fffffffffffffff",
+ "head_uuid": "zzzzz-o0j2j-'$linkuuid'"}'
+</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-fffffffffffffff", "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).
+|_. tail_type→head_type|_. name→head_uuid {properties}|
+|→Collection | _tag name_ → _collection uuid_|
+|→Job | _tag name_ → _job uuid_|
+
+h2. Methods
+
+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%.
-h2. create
+h3. create
Create a new Link.
|_. Argument |_. Type |_. Description |_. Location |_. Example |
|link|object||query||
-h2. delete
+h3. delete
Delete an existing Link.
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
-h2. get
+h3. get
Gets a Link's metadata by UUID.
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
-h2. list
+h3. list
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||
-
-h2. render_not_found
-
-render_not_found links
-
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|a|string||path||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
-h2. update
+h3. update
Update attributes of an existing Link.
projects / arvados.git / blobdiff