---
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://{{ site.arvados_api_host }}/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*|
|provenance|→Collection  |provided → _collection uuid_
{url→http://example.com/foo.tgz, retrieved_at→1352616640.000}||
|provenance|Job→Collection     |provided → _collection uuid_||
|provenance|Specimen→Collection|provided → _collection uuid_||
|provenance|Human→Specimen     |provided → _specimen uuid_||
|provenance|Human→Collection   |provided → _collection uuid_||
|human_trait|Human→Trait  |measured → _trait uuid_ {value→1.83, unit→metre, measured_at→1352616640.000}||
|identifier|→Human        |hu123456 → _human uuid_||
|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.