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

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "links"
   6
   7 ...
   8 {% comment %}
   9 Copyright (C) The Arvados Authors. All rights reserved.
  10
  11 SPDX-License-Identifier: CC-BY-SA-3.0
  12 {% endcomment %}
  13
  14 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/links@
  15
  16 Object type: @o0j2j@
  17
  18 Example UUID: @zzzzz-o0j2j-0123456789abcde@
  19
  20 h2. Resource
  21
  22 Links are an extensible way to describe relationships between Arvados objects and metadata about individual objects.
  23
  24 Each link has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
  25
  26 table(table table-bordered table-condensed).
  27 |_. Attribute|_. Type|_. Description|
  28 |head_uuid|string|The object being described or acted on.|
  29 |tail_uuid|string|The origin or actor in the description or action (may be null).|
  30 |link_class|string|Type of link|
  31 |name|string|Primary value of the link.|
  32 |properties|hash|Additional information, expressed as a key&rarr;value hash. Key: string. Value: string, number, array, or hash.  May be used in queries using "subproperty filters":{{site.baseurl}}/api/methods.html#subpropertyfilters|
  33
  34 h2. Link classes
  35
  36 Some classes are pre-defined by convention and have standard meanings attached to names.
  37
  38 h3. permission
  39
  40 See "permission links":{{site.baseurl}}/api/permission-model.html#links section of the permission model.
  41
  42 h3. star
  43
  44 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).
  45
  46 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.
  47
  48 The schema for a star link is:
  49
  50 table(table table-bordered table-condensed).
  51 |_. Field|_. Value|_. Description|
  52 |tail_uuid|user or group uuid|Either the user that owns the favorite, or the "All Users" group for public favorites.|
  53 |head_uuid|project uuid|The project being favorited|
  54 |link_class|string of value "star"|Indicates this represents a link to a user favorite|
  55
  56 h4. Creating a public favorite
  57
  58 @tail_uuid@ is either an individual user, or the "All Users" group.  The @head_uuid@ is the project being favorited.
  59
  60 <pre>
  61 $ linkuuid=$(arv --format=uuid link create --link '{
  62     "link_class": "star",
  63     "owner_uuid": "zzzzz-tpzed-000000000000000",
  64     "tail_uuid": "zzzzz-j7d0g-fffffffffffffff",
  65     "head_uuid":  "zzzzz-j7d0g-theprojectuuid"}')
  66
  67 $ arv link create --link '{
  68     "link_class": "permission",
  69     "name": "can_read",
  70     "tail_uuid": "zzzzz-j7d0g-fffffffffffffff",
  71     "head_uuid":  "zzzzz-o0j2j-'$linkuuid'"}'
  72 </pre>
  73
  74 h4. Removing a favorite
  75
  76 <pre>
  77 $ arv link delete --uuid zzzzz-o0j2j-thestarlinkuuid
  78 </pre>
  79
  80 h4. Listing favorites
  81
  82 To list all 'star' links that will be displayed for a user:
  83
  84 <pre>
  85 $ arv link list --filters '[
  86   ["link_class", "=", "star"],
  87   ["tail_uuid", "in", ["zzzzz-j7d0g-fffffffffffffff", "zzzzz-tpzed-currentuseruuid"]]]'
  88 </pre>
  89
  90 h3. tag
  91
  92 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.
  93
  94 table(table table-bordered table-condensed).
  95 |_. tail_type&rarr;head_type|_. name&rarr;head_uuid {properties}|
  96 |&rarr;Collection           | _tag name_ &rarr; _collection uuid_|
  97 |&rarr;Job                  | _tag name_ &rarr; _job uuid_|
  98
  99 h2. Methods
 100
 101 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
 102
 103 Required arguments are displayed in %{background:#ccffcc}green%.
 104
 105 h3. create
 106
 107 Create a new Link.
 108
 109 Arguments:
 110
 111 table(table table-bordered table-condensed).
 112 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 113 |link|object||query||
 114
 115 h3. delete
 116
 117 Delete an existing Link.
 118
 119 Arguments:
 120
 121 table(table table-bordered table-condensed).
 122 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 123 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
 124
 125 h3. get
 126
 127 Gets a Link's metadata by UUID.
 128
 129 Arguments:
 130
 131 table(table table-bordered table-condensed).
 132 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 133 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
 134
 135 h3. list
 136
 137 List links.
 138
 139 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
 140
 141 h3. update
 142
 143 Update attributes of an existing Link.
 144
 145 Arguments:
 146
 147 table(table table-bordered table-condensed).
 148 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 149 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
 150 |link|object||query||