10346: Document token scopes.

[arvados.git] / doc / api / methods / links.html.textile.liquid

---
layout: default
navsection: api
navmenu: API Methods
title: "links"

...

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

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

Required arguments are displayed in %{background:#ccffcc}green%.

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|
|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|
|properties|hash|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  |{white-space:nowrap}. can_manage → _group uuid_|The User can read, write, and control permissions on the Group itself, every object owned by the Group, and every object on which the Group has _can_manage_ permission.|
|User→Group  |can_read → _group uuid_  |The User can retrieve the Group itself and every object that is readable by the Group.|
|User→Job|can_write → _job uuid_  |The User can read and update the Job. (This works for all objects, not just jobs.)|
|User→Job|can_manage → _job uuid_  |The User can read, update, and change permissions for the Job. (This works for all objects, not just jobs.)|
|Group→Job|can_manage → _job uuid_  |Anyone with _can_manage_ permission on the Group can also read, update, and change permissions for the Job. Anyone with _can_read_ permission on the Group can read the Job. (This works for all objects, not just jobs.)|

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_||


h2. Methods
h3. create

Create a new Link.

Arguments:

table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
|link|object||query||

h3. delete

Delete an existing Link.

Arguments:

table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||

h3. get

Gets a Link's metadata by UUID.

Arguments:

table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||

h3. list

List links.

Arguments:

table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
|limit|integer (default 100)|Maximum number of links to return.|query||
|order|string|Order in which to return matching links.|query||
|filters|array|Conditions for filtering links.|query||

h3. render_not_found

render_not_found links

Arguments:

table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|a|string||path||

h3. update

Update attributes of an existing Link.

Arguments:

table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
|link|object||query||