doc/api/Links.textile

   1 ---
   2 layout: default
   3 navsection: api
   4 title: "Resource: Links"
   5 navorder: 17
   6 ---
   7
   8 h1. Links
   9
  10 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).
  11
  12 table(table table-bordered table-condensed).
  13 |tail (object)| _class, name_
  14 &rarr;
  15  _properties{}_ |head (object)|
  16
  17 h2. Methods
  18
  19 See "REST methods for working with Arvados resources":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":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&rarr;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 table(table table-bordered table-condensed).
  42 |*link_class*|*tail_type&rarr;head_type*|*name&rarr;head_uuid {properties}*|*Notes*|
  43 |provenance|&rarr;Collection  |provided &rarr; _collection uuid_
  44 {url&rarr;http://example.com/foo.tgz, retrieved_at&rarr;1352616640.000}||
  45 |provenance|Job&rarr;Collection     |provided &rarr; _collection uuid_||
  46 |provenance|Specimen&rarr;Collection|provided &rarr; _collection uuid_||
  47 |provenance|Human&rarr;Specimen     |provided &rarr; _specimen uuid_||
  48 |provenance|Human&rarr;Collection   |provided &rarr; _collection uuid_||
  49 |human_trait|Human&rarr;Trait  |measured &rarr; _trait uuid_ {value&rarr;1.83, unit&rarr;metre, measured_at&rarr;1352616640.000}||
  50 |identifier|&rarr;Human        |hu123456 &rarr; _human uuid_||
  51 |permission|User&rarr;Group  |can_manage &rarr; _group uuid_|Writable only by a user who can_manage this group|
  52 |permission|User&rarr;Group  |can_read &rarr; _group uuid_  |Writable only by a user who can_manage this group.
  53 Gives permission to read any object owned by this group.|
  54 |resources|User&rarr;Collection|wants &rarr; _collection uuid_    |Determines whether data can be deleted|
  55 |resources|User&rarr;Job       |wants &rarr; _job uuid_    |Determines whether a job can be cancelled|
  56
  57 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.