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 The significance of permission links is discussed in the "permission links":{{site.baseurl}}/api/permission-model.html#links section of the permission model documentation.
  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 "Public favorites" project.  These are favorites 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 "Public favorites" group.|
  53 |tail_uuid|user or group uuid|Should be the same as owner_uuid|
  54 |head_uuid|project uuid|The project being favorited|
  55 |link_class|string of value "star"|Indicates this represents a link to a user favorite|
  56
  57 h4. Creating a public favorite
  58
  59 @owner_uuid@ is either an individual user, or the "Public favorites" group.  The @head_uuid@ is the project being favorited.
  60
  61 <pre>
  62 $ linkuuid=$(arv --format=uuid link create --link '{
  63     "link_class": "star",
  64     "owner_uuid": "zzzzz-j7d0g-publicfavorites",
  65     "tail_uuid": "zzzzz-j7d0g-publicfavorites",
  66     "head_uuid":  "zzzzz-j7d0g-theprojectuuid"}')
  67 </pre>
  68
  69 h4. Removing a favorite
  70
  71 <pre>
  72 $ arv link delete --uuid zzzzz-o0j2j-thestarlinkuuid
  73 </pre>
  74
  75 h4. Listing favorites
  76
  77 To list all 'star' links that will be displayed for a user:
  78
  79 <pre>
  80 $ arv link list --filters '[
  81   ["link_class", "=", "star"],
  82   ["tail_uuid", "in", ["zzzzz-j7d0g-publicfavorites", "zzzzz-tpzed-currentuseruuid"]]]'
  83 </pre>
  84
  85 h3. tag
  86
  87 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.
  88
  89 table(table table-bordered table-condensed).
  90 |_. tail_type&rarr;head_type|_. name&rarr;head_uuid {properties}|
  91 |&rarr;Collection           | _tag name_ &rarr; _collection uuid_|
  92 |&rarr;Job                  | _tag name_ &rarr; _job uuid_|
  93
  94 h3. published_port
  95
  96 A **published_port** link enables external access to container ports via user-defined domain names.
  97
  98 If the cluster is configured as follows to forward HTTP requests from external clients to container ports:
  99
 100 <pre>
 101 Services:
 102   ContainerWebServices:
 103     ExternalURL: https://*.containers.zzzzz.example.com/
 104 </pre>
 105
 106 A user can create the following link to route HTTP requests like @https://servicename.containers.zzzzz.example.com/@ to port 12345 in the container running for container request @zzzzz-xvhdp-012340123401234@:
 107
 108 <pre>
 109 {
 110   "link_class" "published_port",
 111   "head_uuid": "zzzzz-xvhdp-012340123401234",
 112   "name": "servicename",
 113   "properties": {
 114     "port": 12345
 115   }
 116 }
 117 </pre>
 118
 119 Refer to the "documentation about published ports":container_requests.html#published_ports for additional information.
 120
 121 h2. Methods
 122
 123 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
 124
 125 Required arguments are displayed in %{background:#ccffcc}green%.
 126
 127 h3. create
 128
 129 Create a new Link.
 130
 131 Arguments:
 132
 133 table(table table-bordered table-condensed).
 134 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 135 |link|object||query||
 136
 137 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.
 138
 139 h3. delete
 140
 141 Delete an existing Link.
 142
 143 Arguments:
 144
 145 table(table table-bordered table-condensed).
 146 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 147 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
 148
 149 When you delete a permission link, any other existing permission links that have the same @head_uuid@ and @tail_uuid@ are also deleted.
 150
 151 h3. get
 152
 153 Gets a Link's metadata by UUID.
 154
 155 Arguments:
 156
 157 table(table table-bordered table-condensed).
 158 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 159 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
 160
 161 h3. list
 162
 163 List links.
 164
 165 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
 166
 167 h3. update
 168
 169 Update attributes of an existing Link.
 170
 171 Arguments:
 172
 173 table(table table-bordered table-condensed).
 174 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 175 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
 176 |link|object||query||
 177
 178 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.
 179
 180 h3. get_permissions
 181
 182 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.
 183
 184 Arguments:
 185
 186 table(table table-bordered table-condensed).
 187 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 188 {background:#ccffcc}.|uuid|string|The UUID of the object.|path||