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 "All Users" group, these will be displayed to all users that have permission to read the project that has been favorited.
  47
  48 The schema for a star link is:
  49
  50 table(table table-bordered table-condensed).
  51 |_. Field|_. Value|_. Description|
  52 |owner_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 favorite
  57
  58 @owner_uuid@ is either an individual user, or the "All Users" group.  The @head_uuid@ is the project being favorited.
  59
  60 <pre>
  61 $ arv link create --link '{
  62     "owner_uuid": "zzzzz-j7d0g-fffffffffffffff",
  63     "head_uuid":  "zzzzz-j7d0g-theprojectuuid",
  64     "link_class": "star"}'
  65 </pre>
  66
  67 h4. Deleting a favorite
  68
  69 <pre>
  70 $ arv link delete --uuid zzzzz-o0j2j-thestarlinkuuid
  71 </pre>
  72
  73 h4. Listing favorites
  74
  75 To list all 'star' links that will be displayed for a user:
  76
  77 <pre>
  78 $ arv link list --filters '[
  79   ["link_class", "=", "star"],
  80   ["owner_uuid", "in", ["zzzzz-j7d0g-fffffffffffffff", "zzzzz-tpzed-currentuseruuid"]]]'
  81 </pre>
  82
  83 h3. tag
  84
  85 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.
  86
  87 table(table table-bordered table-condensed).
  88 |_. tail_type&rarr;head_type|_. name&rarr;head_uuid {properties}|
  89 |&rarr;Collection           | _tag name_ &rarr; _collection uuid_|
  90 |&rarr;Job                  | _tag name_ &rarr; _job uuid_|
  91
  92 h2. Methods
  93
  94 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
  95
  96 Required arguments are displayed in %{background:#ccffcc}green%.
  97
  98 h3. create
  99
 100 Create a new Link.
 101
 102 Arguments:
 103
 104 table(table table-bordered table-condensed).
 105 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 106 |link|object||query||
 107
 108 h3. delete
 109
 110 Delete an existing Link.
 111
 112 Arguments:
 113
 114 table(table table-bordered table-condensed).
 115 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 116 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
 117
 118 h3. get
 119
 120 Gets a Link's metadata by UUID.
 121
 122 Arguments:
 123
 124 table(table table-bordered table-condensed).
 125 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 126 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
 127
 128 h3. list
 129
 130 List links.
 131
 132 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
 133
 134 h3. update
 135
 136 Update attributes of an existing Link.
 137
 138 Arguments:
 139
 140 table(table table-bordered table-condensed).
 141 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 142 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
 143 |link|object||query||