Whole Brain Catalog Server API

From Whole Brain Catalog

Jump to: navigation, search

This is work in progress by David Little.

Contents

[edit] Overview

The Whole Brain Catalog (WBC) server uses the HTTP protocol and its GET, PUT, POST, and DELETE functions.

In the case of GET functions, the server returns an XML document or a content object which may be binary or text data. The XML documents adhere to the XML schema documented here. Binary data may be some sort of image, for example, and text data might be coordinate or time-series data points.

In all of the cases that follow [server:port] refers to the server's URL including the port. If the port is omitted the function defaults to the standard HTTP port 80. For example,

  • http://data.wholebraincatalog.org/
  • http://henry.ucsd.edu:8182

[edit] Content Object

  • A Content Object could be a binary or text object.
  • The object is stored on the server as a data file.
  • It may be an image or a data set.

[edit] GET

Content Object
HTTP
Function		 GET
Purpose To retrieve a Content Object from the server.
Prototype http://data.wholebraincatalog.org/content/[contentObjectFileName]
Success
status
code		 200 OK
Return
type and
content		 File: The requested Content Object.
Comments

contentObjectFileName

  • Required.
  • Case-sensitive.
  • Value: The Content Object file name.
Example http://data.wholebraincatalog.org/content/retina.obj
Failure
status
codes
  • 404 Not Found. The object did not exist on the server.
  • 500 Internal Server Error. A server error occurred while trying to replace the object.


[edit] PUT

Content Object
HTTP
Function		 PUT
Purpose To import (upload) a content object from the client to the server. The server generates a non-duplicate file name if necessary, adds the object to the server's data files, creates and inserts a Data Wrapper into the database, and responds to the client with the Data Wrapper' URI (id).
Prototype http://data.wholebraincatalog.org/content/[contentObjectFileName]
Success
status
code		 201 Created
Return
type and
content		 Text: The imported object's new Data Wrapper URI (id).
Comments

contentObjectFileName

  • Required.
  • Case-sensitive.
  • Value: The proposed file name of the Content Object. If the proposed file name is a duplicate of an existing file, the file name will be altered to be unique.
Example http://data.wholebraincatalog.org/content/retina.obj
Failure
status
codes		 500 Internal Server Error. A server error occurred while trying to add the object or its Data Wrapper.


[edit] POST

Content Object
HTTP
Function		 POST
Purpose To replace an existing Content Object on the server. The server replaces the object to the server's data files, and responds to the client with the object's Data Wrapper URI (id).
Prototype http://data.wholebraincatalog.org/content/[contentObjectFileName]
Success
status
code		 200 OK
Return
type and
content		 Text: The imported object's Data Wrapper URI (id).
Comments

contentObjectFileName

  • Required.
  • Case-sensitive.
  • Value: The Content Object's file name.
Example http://data.wholebraincatalog.org/content/retina.obj
Failure
status
codes
  • 404 Not Found. The object did not exist on the server.
  • 500 Internal Server Error. A server error occurred while trying to replace the object.


[edit] DELETE

Content Object
HTTP
Function		 DELETE
Purpose To remove an existing Content Object from the server. The server removes the object from the server's data files and deletes the object's Data Wrapper from the database.
Prototype http://data.wholebraincatalog.org/content/[contentObjectFileName]
Success
status
code		 200 OK
Return
type and
content		 (No content is returned.)
Comments

contentObjectFileName

  • Required.
  • Case-sensitive.
  • Value: The Content Object's file name.
Example http://data.wholebraincatalog.org/content/retina.obj
Failure
status
codes
  • 404 Not Found. The object did not exist on the server.
  • 500 Internal Server Error. A server error occurred while trying to remove the object or delete its Data Wrapper.


[edit] Data Wrappers

Data Wrapper
HTTP
Function		 GET
Purpose To retrieve a data wrapper which references some content object such as an image. The data wrapper contains information needed to retrieve the object.
Prototype http://data.wholebraincatalog.org/datawrappers/[dataType]/[datawrapperId]
Success
status
code		 200 OK
Return
type and
content		 XML document. See the schema.
Comments

dataType

  • Optional. If omitted, the result will be a list of data wrappers of all types.
  • Case-sensitive.
  • Value: generic | mesh | morphml | neuroml.

dataWrapperId

  • Optional. If omitted, the result will be a list of data wrappers of the dataType specified.
  • Case-sensitive.
  • Value: A random server-specific data wrapper identifier.
Example

http://data.wholebraincatalog.org/datawrappers
http://data.wholebraincatalog.org/datawrappers/generic
http://data.wholebraincatalog.org/datawrappers/generic/betom

Failure
status
codes


[edit] Schema

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<xs:schema xmlns="http://wholebrainproject.org/wbc/generated"
	xmlns:meta="http://morphml.org/metadata/schema" xmlns:net="http://morphml.org/networkml/schema"
	xmlns:nml="http://morphml.org/neuroml/schema"
	xmlns:ts="http://wholebrainproject.org/wbc/generated/timeseries"
	xmlns:anno="http://wholebrainproject.org/wbc/generated/annotation"
	
	xmlns:dw="http://wholebrainproject.org/wbc/generated/datawrapper"
	xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
	targetNamespace="http://wholebrainproject.org/wbc/generated">

	<xs:import namespace="http://morphml.org/neuroml/schema"
		schemaLocation="NeuroML_Level3_v1.7.3.xsd"/>
	<xs:import namespace="http://morphml.org/networkml/schema" schemaLocation="NetworkML_v1.7.3.xsd"/>
	<xs:import namespace="http://morphml.org/metadata/schema" schemaLocation="Metadata_v1.7.3.xsd"/>
	<xs:import namespace="http://wholebrainproject.org/wbc/generated/timeseries"
	schemaLocation="WBC_TimeSeries_v0.1.xsd"/>
	<xs:import namespace="http://wholebrainproject.org/wbc/generated/annotation"
	schemaLocation="WBC_Annotation_v0.4.xsd"/>
	<xs:import namespace="http://wholebrainproject.org/wbc/generated/datawrapper"
		schemaLocation="WBC_DataWrapper_v0.4.xsd"/>

  <xs:element minOccurs="0" name="DataWrappers">
  	<xs:annotation>
  		<xs:documentation>Defines a set of data items that are available to the
  			  WBC</xs:documentation>
  	</xs:annotation>
  	<xs:complexType>
  		<xs:sequence>

  			<xs:element maxOccurs="unbounded" minOccurs="1" name="DataWrapper"> 
          <xs:complexType>
            <xs:annotation>
              <xs:documentation>Metadata describing a data item. Note that this is intended to
                  describe some kind of complex data that is generally external to the system.
                  DataWrappers can be associated with a tangible in order to appear within a
                  particular place in the Whole Brain Catalog</xs:documentation>
            </xs:annotation>
            <xs:sequence>
              <xs:choice>
                <xs:annotation>
                  <xs:documentation>Choose between assigning a simple URL location, a 
                      web service location, or embedding the content in a content tag</xs:documentation>
                </xs:annotation>

                <xs:element name="location" type="xs:anyURI">
                  <xs:annotation>
                    <xs:documentation>A URI location, which may vary depending on the data
                        type</xs:documentation>
                  </xs:annotation>
                </xs:element>

                <xs:element name="webServiceLocation">
                  <xs:complexType>
                    <xs:sequence>

                      <xs:element name="hostName" type="xs:string" minOccurs="1" maxOccurs="1">
                        <xs:annotation>
                          <xs:documentation>A host name for the service, e.g.
                              132.239.131.188 </xs:documentation>
                        </xs:annotation>
                      </xs:element>

                      <xs:element name="serviceName" type="xs:string" minOccurs="1"
                          maxOccurs="1">
                        <xs:annotation>
                          <xs:documentation>A service name at the host, e.g. abasagittal.
                              Currently we seem to use one service name per image.
                          </xs:documentation>
                        </xs:annotation>
                      </xs:element>
                      
                    </xs:sequence>
                  </xs:complexType>
                </xs:element>

                <xs:element name="ccdbLocation">
                	<xs:annotation>
                		<xs:documentation>
                			Location of a data file that resides on the Cell Centered database (http://ccdb.ucsd.edu)
                		</xs:documentation>
                	</xs:annotation>
                	<xs:complexType>
                		<xs:sequence>

                			<xs:element type="xs:string" name="MPID" minOccurs="1" maxOccurs="1">
                				<xs:annotation>
                					<xs:documentation>The Microscopy Product ID from the Cell centered database</xs:documentation>
                				</xs:annotation>
                			</xs:element>

                			<xs:element type="xs:string" name="DataID" minOccurs="1" maxOccurs="1">
                  			<xs:annotation><xs:documentation>References a specific data item within an MPID record in the CCDB</xs:documentation></xs:annotation>
                			</xs:element>

                		</xs:sequence>
                	</xs:complexType>
                </xs:element>

                <xs:element name="content">
                  <xs:complexType>
                    <xs:choice>
                      <xs:element name="Level3Cell" type="nml:Level3Cell"/>
                      <xs:element name="NeuroML" type="nml:NeuroMLLevel3"/>
                      <xs:element name="TimeSeries" type="ts:TimeSeriesMappingSet"/>
                    </xs:choice>
                  </xs:complexType>
                </xs:element>

              </xs:choice>
                
              <xs:element name="annotation" type="anno:annotationType" 
                  minOccurs="0" maxOccurs="unbounded"/>
  
              <xs:element name="type" type="xs:Name" minOccurs="1">
                <xs:annotation>
                  <xs:documentation> The type of data that will be found at the location.
                      Importers declare types. This element may go away... </xs:documentation>
                </xs:annotation>
              </xs:element>

            </xs:sequence>

            <xs:attribute name="id" type="xs:anyURI">
            <xs:attribute name="semanticInstanceId" type="xs:anyURI" use="optional">
              <xs:annotation>
                <xs:documentation>URI of the ontology instance associated with this
                </xs:documentation>
              </xs:annotation>
            </xs:attribute>
          </xs:complexType>

    		</xs:element>

    	</xs:sequence>
   	</xs:complexType>

  </xs:element>


    <xs:complexType name="TimeSeriesMappingSet">
        <xs:annotation>
            <xs:documentation>A sequence of TimeSeriesMapping elements</xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="timeSeries" type="TimeSeriesMapping" minOccurs="1"
                maxOccurs="unbounded">
    <xs:complexType name="TimeSeriesMapping">
        <xs:annotation>
            <xs:documentation>Describes time series data to combine with NeuroML
                files</xs:documentation>
        </xs:annotation>
        <xs:choice>
            <xs:element name="cellspikes" type="xs:string" minOccurs="0" maxOccurs="1">
                <xs:annotation>
                    <xs:documentation>
                        A comma seperated list of integers that represent the number of milliseconds till spike time.
                        the neuron spikes
                    </xs:documentation>
                </xs:annotation>
            </xs:element>
            <xs:sequence>
                <xs:element name="segmentId" type="xs:nonNegativeInteger" minOccurs="1" maxOccurs="1">
                    <xs:annotation>
                        <xs:documentation>The NeuroML segment id for where the time series data
                            belongs</xs:documentation>
                    </xs:annotation>
                </xs:element>
                <xs:element name="times" type="xs:string" minOccurs="1" maxOccurs="1">
                    <xs:annotation>
                        <xs:documentation>A comma separated set of strings that contain floats which
                            define the time points. There should be as many items in this list as the
                            voltageSeries list.</xs:documentation>
                    </xs:annotation>
                </xs:element>
                <xs:element name="voltages" type="xs:string" minOccurs="1" maxOccurs="1">
                    <xs:annotation>
                        <xs:documentation>A comma separated set of strings that contain floats which
                            define the voltage values at each corresponding time point in the timeSeries
                            tag. There should be as many items in this list as in the timeSeries
                            list.</xs:documentation>
                    </xs:annotation>
                </xs:element>
            </xs:sequence>
        </xs:choice>
        
        <xs:attribute name="name" type="xs:string" use="optional">
            <xs:annotation>
                <xs:documentation>An optional name to give this time series.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name="id" type="xs:anyURI" use="optional">
            <xs:annotation>
                <xs:documentation>The unique URI that defines this time series. This is optional
                    because data may come into the WBC without a URI and require that one be
                    provided.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
    </xs:complexType>
    
                </xs:element>
        </xs:sequence>
    </xs:complexType>
    
    <!-- Definition of a Time series follows. -->
</xs:schema>

[edit] Layers

Layers
HTTP
Function		 GET
Purpose To retrieve a specific layer or a list of all layers.
Prototype http://[server:port]/layers/[layerId]
Success
status
code		 200 OK
Return
type and
content		 XML document. See the schema.
Comments

layerId

  • Optional. If omitted, the result will be a list of all layers.
  • Case-sensitive.
  • Value: A random server-specific layer identifier.
Example

http://data.wholebraincatalog.org/layers
http://data.wholebraincatalog.org/layers/gwv9h

Failure
status
codes


[edit] Schema

  • For a list of layers the root element is Layers
  • For a specific layer the root element is LayerState 
<xs:schema xmlns="http://wholebrainproject.org/wbc/generated"
  xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
    targetNamespace="http://wholebrainproject.org/wbc/generated">
  <xs:element minOccurs="0" name="Layers">
    <xs:annotation>
      <xs:documentation>Defines a set of LayerState elements.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element maxOccurs="unbounded" minOccurs="1" name="LayerState">
          <xs:complexType name="LayerState">
            <xs:annotation>
              <xs:documentation> Describes a Layer for WBC. Defines a collection of tangibles in a
                scene whose visibility is linked. Users are allowed to add particular collections of
                data to their own layers. Layers are all publicly viewable. Individual users can
                elect to turn off a layer, but by default they are all visible. Includes a
                NeuroMLLevel3 from morphml.org and adds a set of curves and a set of slides, as well
                as an id attribute. </xs:documentation>
            </xs:annotation>
            <xs:sequence>
              <xs:element minOccurs="0" name="tangibleIds">
                <xs:complexType>
                  <xs:annotation>
                    <xs:documentation>Set of Tangibles</xs:documentation>
                  </xs:annotation>
                  <xs:sequence>
                    <xs:element maxOccurs="unbounded" name="tangibleId" type="xs:anyURI">
                      <xs:annotation>
                        <xs:documentation>A single tangible id reference.</xs:documentation>
                      </xs:annotation>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
            <xs:attribute name="id" type="xs:anyURI" use="required"/>
            <xs:attribute name="name" type="xs:Name"/>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

[edit] Tangibles

[edit] GET

Tangibles
HTTP
Function		 GET
Purpose To retrieve a specific Tangible, a list of Tangibles of a specified type, or a list of all Tangibles.
Prototype http://[server:port]/tangibles/[tangibleType]/[tangibleId]
Success
status
code		 200 OK
Return
type and
content		 XML document. See the schema.
Comments

tangibleType

  • Optional. If omitted, the result will be a list of tangibles of all types.
  • Case-sensitive.
  • Value: brainregions | cellinstances | curveanchorpoints | curves | meshmodels | slides | volumes.

tangibleId

  • Optional. If omitted, the result will be a list of tangibles of the tangibleType specified.
  • Case-sensitive.
  • Value: A random server-specific tangible identifier.
Example

http://data.wholebraincatalog.org/tangibles
http://data.wholebraincatalog.org/tangibles/slides
http://data.wholebraincatalog.org/tangibles/slides/w5ncp

Failure
status
codes


[edit] DELETE

Tangibles
HTTP
Function		 DELETE
Purpose To delete a Tangible identifier, from a given Layer.
Prototype http://[server:port]/tangibles/[tangibleType]/[tangibleId]/[layerId]
Success
status
code		 200 OK
Return
type and
content		 (No content is returned.)
Comments

tangibleType

  • Required.
  • Case-sensitive.
  • Value: brainregions | cellinstances | curveanchorpoints | curves | meshmodels | slides | volumes.

tangibleId

  • Required.
  • Case-sensitive.
  • Value: A random server-specific tangible identifier.

layerId

  • Required.
  • Case-sensitive.
  • Value: A random server-specific layer identifier.
Example

http://data.wholebraincatalog.org/tangibles/slides/w5ncp/axuhm
The tangibleId w5ncp will be deleted from layer axuhm. The tangible itself is not deleted.

Failure
status
codes
  • 404 Not Found. The tangibleId did not exist in given Layer.
  • 500 Internal Server Error. A server error occurred while trying to remove the object or delete its Data Wrapper.


[edit] Users

Users
HTTP
Function		 GET
Purpose To retrieve a specific user or a list of all users.
Prototype http://[server:port]/users/[userId]
Success
status
code		 200 OK
Return
type and
content		 XML document. See the schema.
Comments

userId

  • Optional. If omitted, the result will be a list of all users.
  • Case-sensitive.
  • Value: default | user identifier.
Example

http://data.wholebraincatalog.org/users
http://data.wholebraincatalog.org/users/default http://data.wholebraincatalog.org/users/abcdef

Failure
status
codes


Retrieved from "http://wiki.wholebraincatalog.org/wiki/Whole_Brain_Catalog_Server_API"
Personal tools