Merge remote-tracking branch 'origin' into 1786-replace-jekyll-with-zenweb

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

diff --git a/doc/api/schema/Link.textile b/doc/api/schema/Link.textile
index a1252fb7689c39cfc0c100ded4df566609101da6..117c10cb164e921e4d6065492a350f75e646481e 100644 (file)
--- a/doc/api/schema/Link.textile
+++ b/doc/api/schema/Link.textile
@@ -2,41 +2,86 @@
 layout: default
 navsection: api
 navmenu: Schema
-title: "Resource: Link"
-navorder: 13
----
+title: Link
+navorder: 12
+...
 
 h1. Link
 
-A **Link** represents...
+**Links** describe relationships between Arvados objects, and from objects to primitives.
+
+Links are directional: each metadata object has a tail (subject), class, name, properties, and head (object or value).  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":methods.html
+See "REST methods for working with Arvados resources":/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":/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.
 
-API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/link@
+h3. provenance
 
-h2. Creation
+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
 
-h3. Prerequisites
+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|
 
-Prerequisites for creating a Link.
+h3. tag
 
-h3. Side effects
+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.
 
-Side effects of creating a Link.
+table(table table-bordered table-condensed).
+|_. tail_type→head_type|_. name→head_uuid {properties}|
+|→Collection           | _tag name_ → _collection uuid_|
+|→Job                  | _tag name_ → _job uuid_|
 
-h2. Resources
+h3. human_trait
 
-Each Link has, in addition to the usual "attributes of Arvados resources":resources.html:
+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).
-|*Attribute*|*Type*|*Description*|*Example*|
-|tail_uuid|string|||
-|tail_kind|string|||
-|link_class|string|||
-|name|string|||
-|head_uuid|string|||
-|properties|Hash|||
-|updated_at|datetime|||
-|head_kind|string|||
+|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
+|→Human        |hu123456 → _human uuid_||
+