Merge branch 'master' into 2051-nondeterministic-jobs

[arvados.git] / doc / api / schema / Link.html.textile.liquid

---
layout: default
navsection: api
navmenu: Schema
title: Link

...



**Links** describe relationships between Arvados objects, and from objects to primitives.

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.

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.

h2. Methods

See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html

API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/links@

h2. Resource

Each link has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:

table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|
|tail_uuid|string|Object UUID at the tail (start, source, origin) of this link|
|tail_kind|string|Object kind at the tail (start, source, origin) of this link|
|link_class|string|Class (see below)|
|name|string|Link type (see below)|
|head_uuid|string|Object UUID at the head (end, destination, target) of this link|
|head_kind|string|Object kind at the head (end, destination, target) of this link|
|properties{}|list|Additional information, expressed as a key→value hash. Key: string. Value: string, number, array, or hash.|

h2. Link classes

Some classes are pre-defined by convention and have standard meanings attached to names.

h3. provenance

table(table table-bordered table-condensed).
|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
|→Collection  |provided → _collection uuid_
{url→http://example.com/foo.tgz, retrieved_at→1352616640.000}||
|Job→Collection     |provided → _collection uuid_||
|Specimen→Collection|provided → _collection uuid_||
|Human→Specimen     |provided → _specimen uuid_||
|Human→Collection   |provided → _collection uuid_||

h3. permission

table(table table-bordered table-condensed).
|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
|User→Group  |can_manage → _group uuid_|Writable only by a user who can_manage this group|
|User→Group  |can_read → _group uuid_  |Writable only by a user who can_manage this group.
Gives permission to read any object owned by this group.|

h3. resources

table(table table-bordered table-condensed).
|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
|User→Collection|wants → _collection uuid_    |Determines whether data can be deleted|
|User→Job       |wants → _job uuid_    |Determines whether a job can be cancelled|

h3. tag

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.

table(table table-bordered table-condensed).
|_. tail_type→head_type|_. name→head_uuid {properties}|
|→Collection           | _tag name_ → _collection uuid_|
|→Job                  | _tag name_ → _job uuid_|

h3. human_trait

table(table table-bordered table-condensed).
|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
|Human→Trait  |measured → _trait uuid_ {value→1.83, unit→metre, measured_at→1352616640.000}||

h3. identifier

table(table table-bordered table-condensed).
|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
|→Human        |hu123456 → _human uuid_||