Merge branch 'master' into 2051-nondeterministic-jobs
[arvados.git] / doc / api / schema / Link.html.textile.liquid
1 ---
2 layout: default
3 navsection: api
4 navmenu: Schema
5 title: Link
6
7 ...
8
9
10
11 **Links** describe relationships between Arvados objects, and from objects to primitives.
12
13 Links are directional: each metadata object has a tail (the "subject" being described), class, name, properties, and head (the "object" that describes the "subject").  A Link may describe a relationship between two objects in an Arvados database: e.g. a _permission_ link between a User and a Group defines the permissions that User has to read or modify the Group.  Other Links simply represent metadata for a single object, e.g. the _identifier_ Link, in which the _name_ property represents a human-readable identifier for the object at the link's head.
14
15 For links that don't make sense to share between API clients, a _link_class_ that begins with @client@ (like @client.my_app_id@ or @client.my_app_id.anythinghere@) should be used.
16
17 h2. Methods
18
19 See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
20
21 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/links@
22
23 h2. Resource
24
25 Each link has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
26
27 table(table table-bordered table-condensed).
28 |_. Attribute|_. Type|_. Description|
29 |tail_uuid|string|Object UUID at the tail (start, source, origin) of this link|
30 |tail_kind|string|Object kind at the tail (start, source, origin) of this link|
31 |link_class|string|Class (see below)|
32 |name|string|Link type (see below)|
33 |head_uuid|string|Object UUID at the head (end, destination, target) of this link|
34 |head_kind|string|Object kind at the head (end, destination, target) of this link|
35 |properties{}|list|Additional information, expressed as a key→value hash. Key: string. Value: string, number, array, or hash.|
36
37 h2. Link classes
38
39 Some classes are pre-defined by convention and have standard meanings attached to names.
40
41 h3. provenance
42
43 table(table table-bordered table-condensed).
44 |_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
45 |→Collection  |provided → _collection uuid_
46 {url→http://example.com/foo.tgz, retrieved_at→1352616640.000}||
47 |Job→Collection     |provided → _collection uuid_||
48 |Specimen→Collection|provided → _collection uuid_||
49 |Human→Specimen     |provided → _specimen uuid_||
50 |Human→Collection   |provided → _collection uuid_||
51
52 h3. permission
53
54 table(table table-bordered table-condensed).
55 |_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
56 |User→Group  |can_manage → _group uuid_|Writable only by a user who can_manage this group|
57 |User→Group  |can_read → _group uuid_  |Writable only by a user who can_manage this group.
58 Gives permission to read any object owned by this group.|
59
60 h3. resources
61
62 table(table table-bordered table-condensed).
63 |_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
64 |User→Collection|wants → _collection uuid_    |Determines whether data can be deleted|
65 |User→Job       |wants → _job uuid_    |Determines whether a job can be cancelled|
66
67 h3. tag
68
69 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.
70
71 table(table table-bordered table-condensed).
72 |_. tail_type→head_type|_. name→head_uuid {properties}|
73 |→Collection           | _tag name_ → _collection uuid_|
74 |→Job                  | _tag name_ → _job uuid_|
75
76 h3. human_trait
77
78 table(table table-bordered table-condensed).
79 |_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
80 |Human→Trait  |measured → _trait uuid_ {value→1.83, unit→metre, measured_at→1352616640.000}||
81
82 h3. identifier
83
84 table(table table-bordered table-condensed).
85 |_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
86 |→Human        |hu123456 → _human uuid_||
87