add api/Links

diff --git a/doc/api/Links.textile b/doc/api/Links.textile
new file mode 100644 (file)
index 0000000..c9ff43b
--- /dev/null
+++ b/doc/api/Links.textile
@@ -0,0 +1,53 @@
+---
+layout: default
+navsection: api
+title: API Reference
+navorder: 10
+---
+
+h1. Links
+
+Links encode connections between Orvos 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 [[API REST Methods|REST methods for working with Orvos resources]]
+
+API endpoint base: @https://xyzzy.orvosapi.com/orvos/v1/links@
+
+h2. Resource
+
+Each link has, in addition to the usual [[API Resources|attributes of Orvos resources]]:
+
+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.