add job tasks docs

[arvados.git] / doc / api / Links.textile

---
layout: default
navsection: api
title: "Resource: Links"
navorder: 10
---

h1. Links

Links encode connections between Arvados objects, and from objects to primitives.  Each metadata object has a tail (subject), class, name, properties, and head (object or value).

table(table table-bordered table-condensed).
|tail (object)| _class, name_ 
→
 _properties{}_ |head (object)|

h2. Methods

See "REST methods for working with Arvados resources":methods.html

API endpoint base: @https://xyzzy.arvados.org/arvados/v1/links@

h2. Resource

Each link has, in addition to the usual "attributes of Arvados resources":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.

table(table table-bordered table-condensed).
|*link_class*|*tail_type→head_type*|*name→head_uuid {properties}*|*Notes*|
|data_origin|Collection→string  |retrieved_by → _user uuid_ {url→http://example.com/foo.tgz, retrieved_at→1352616640.000}||
|data_origin|Collection→Job     |output_of → _job uuid_||
|data_origin|Collection→Specimen|derived_from → 4ly9q-2g125-fbzfbavpo4gwpw0||
|human_trait|Human→Trait  |measured → _trait uuid_ {value→1.83, unit→metre, measured_at→1352616640.000}||
|permission|User→Group  |can_manage → _group uuid_|Writable only by a user who can_manage this group|
|permission|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.|
|resources|User→Collection|wants → _collection uuid_    |Determines whether data can be deleted|
|resources|User→Job       |wants → _job uuid_    |Determines whether a job can be cancelled|

For links that don't make sense to share between API clients, a link class like @client.my_app_id@ or @client.my_app_id.anythinghere@ should be used.