From 4163ec22d45e3c742f09b63e6ec6aedde83b5222 Mon Sep 17 00:00:00 2001 From: Tom Clegg Date: Wed, 10 Apr 2013 13:30:01 -0700 Subject: [PATCH] add api/Links --- doc/api/Links.textile | 53 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 doc/api/Links.textile diff --git a/doc/api/Links.textile b/doc/api/Links.textile new file mode 100644 index 0000000000..c9ff43b864 --- /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. -- 2.30.2