The original discussion for the interface  is in DataServer

Database objects are access through the web service Data Service.  This web service is RESTful in it's interface and deals with XML documents.

Basic object types in Bisquik:

#. Image   : An image including it's src and dimensions
#. Tag     : A labeled data item
#. GObject : A graphical objects relative to the image.
#. Dataset : a group of objects


Objects are created by HTTP posting to the Dataservice.   In order to use these services, in many cases
you will need authorization.  This is discussed in BisquikAuthorization.

#. POST  create/append a resource 
#. DELETE   delete a resource
#. GET   fetch a resource  
#. PUT   replace a resource 

It is sometimes best to lead with an example.  Below we show how to create a new image object::

  POST /data_service/image
    <image name="my image" value=""  />
     <image uri="http://host/data_service/images/12" value="" name="my image" />

Note that a uri is added to the image representing the id of Image to be used in later operations.  Also note
that the {{{value}}} address did not change.  ''Image are not actually stored by data service''.  If image storage is
required, then the image service can be used.

Creating tags on images is easy::

  POST /data_service/image/12
  <image uri='/data_service/image/12' >
    <tag name="comment" value="This is a comment" />
    <tag name="name"    value="new" />
     <image uri="http://datahost/ds/images/12" src="" x="512" y="512" z="1" t="1" ch="3" />

Datasets are a little different::

  POST /data_service/dataset
    <dataset  name="Experiment 1" >
        <value type="object">http://datahost/ds/images/12</value>
     <dataset uri="http://datahost/ds/datasets/40" name="Experiment 1" >
          <value index="0" type="object">http://datahost/ds/images/12</value>

You can directly address the elements of the dataset as follows::

   GET /data_service/dataset/40/tags/44/values 
   <resource uri='/data_service/dataset/40/tags/44/values'
     <value index="0" type="object">http://datahost/ds/images/12</value>

Replace elements::
   PUT /ds/datasets/40/tags/44/values 
        <value type="object">http://datahost/ds/images/12</value>
        <value type="object">http://datahost/ds/images/12</value>
        <value type="object">http://datahost/ds/images/12</value>

Other types available::

   /ds/image     : parameters view=[count, full, deep] limit=#, offset=#, tag_query="some tags" 
   /ds/tag      :

Standard query parameters

  Change the output format of the returned resource [short, full, deep], clean, 
  Limit the number of items returned
  used with limit to fetch more items 
  see below.
  Order the response based on the values of a tag
  set the format of the response xml, csv, etc.
resource attributes 
   Resource attributes (name,value,type, hidden, ts, created) can be queried including the use of relational operators::


Tag Query Operations

   #.  Query resources (image) by underlying tag::


   #.  return values list of all experimenters in the above query::

   #. return values list of all available tag names on query::


   #. Combination of value or tag names::
       /image?tag_query="tag1:value1 [and|or] value2"

Tag Special Operations
   #.  Return all tha available tag names for the given superquery::


   #.  all possible values for a particular tag name::


   #. all tags have a name="tag_name" as an attribute::

       /tag/?name=tag_name   : 

   #. all tags having a value attribute of tag_val::

       /tag/?value=tag_val   : 

   #. Extract lots info (names of tags, value of tags with name qq, and types of gobjects 

      /image/?extract=tag[name],tag[value, name="qqq"],gobject[type]

      The syntax is   ?extract=<expr> ::

       <expr> := resource_type [ <attribute>', <filter>,... ] 
       <attribute> := name, value, type
       <filter>  := <attribute> <relop> <literal>
       <relop>   := '='
       <literal>  is a trsint

Tag order operations

 Tag order specifies the sort order of the returned items.  

  #. return images sorted by time stamp(most recent first)::


  #. sorted by a particular tag value::


/data_service/ ::

Return a list of available resources at this root. An example return would be

  <resource uri="" name="image"/>

Each resource returned would be queryable:

/data_service/image ::

Return a list of images available at the site

  <image resource="/images/1" />

Data services are available for all predefined object types:



Return a list of tags representing the names and defualt values


All tags in the database (should be limited to user)


Same as above


List of registered modules

<module name="m1" resource="/module/1/" engine="matlab">
  <tag name="formal-input" value="resource image" />
  <tag name="formal-output" value="resource image" />


A set of values or resource references

User objects

Templates define user groups of objects i.e. groups of tags. A template can be instantiated on

an object (tags are added to current object) or as a separate addressable resource:

Creating a user object

Post a document to a template resource will create a user object.

i.e. If the system has defined the 'microtubule' template then access to instances is available under /microtubule, and

posting the following XML document to /microtuble/

will result in the creation of a new microtubule resource.

  <resource resource_type="microtubule"> 
    <tag name="name" value="mt1" />
    <tag name="cell_type" value="hela" />
    <tag name="track" >
        <gobject type="mt_track">
            <point x="100" y="100" t="0" >

The result of the post will be the create resource

   <resource resource_type="microtubule" uri="/microtubule/1" />

Retrieving a user object

Example. A microtubule template consists of several tags:

name string cell_type string track resource (gobject)

  <resource resource_type="microtubule">
    <tag name="name" value="mt1" />
    <tag name="cell_type" value="hela" />
    <tag name="track" value="/gobject/2" />

Last modified 4 years ago Last modified on 10/20/2016 04:43:19 PM