Merge branch 'master' into 13804-no-shutdown-wanted-nodes
[arvados.git] / 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→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. tag
43
44 A **tag** link describes an object using an unparsed plain text string. Tags can be used to annotate objects that are not editable, like collections and objects shared as read-only.
45
46 table(table table-bordered table-condensed).
47 |_. tail_type→head_type|_. name→head_uuid {properties}|
48 |→Collection           | _tag name_ → _collection uuid_|
49 |→Job                  | _tag name_ → _job uuid_|
50
51 h2. Methods
52
53 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
54
55 Required arguments are displayed in %{background:#ccffcc}green%.
56
57 h3. create
58
59 Create a new Link.
60
61 Arguments:
62
63 table(table table-bordered table-condensed).
64 |_. Argument |_. Type |_. Description |_. Location |_. Example |
65 |link|object||query||
66
67 h3. delete
68
69 Delete an existing Link.
70
71 Arguments:
72
73 table(table table-bordered table-condensed).
74 |_. Argument |_. Type |_. Description |_. Location |_. Example |
75 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
76
77 h3. get
78
79 Gets a Link's metadata by UUID.
80
81 Arguments:
82
83 table(table table-bordered table-condensed).
84 |_. Argument |_. Type |_. Description |_. Location |_. Example |
85 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
86
87 h3. list
88
89 List links.
90
91 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
92
93 h3. update
94
95 Update attributes of an existing Link.
96
97 Arguments:
98
99 table(table table-bordered table-condensed).
100 |_. Argument |_. Type |_. Description |_. Location |_. Example |
101 {background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
102 |link|object||query||