Bioshare Web Services API

The goal of the Bioshare API is to provide a consistent and simple interface to Bioshare resources on a per user basis. This will allow other applications to be written in arbitrary languages, platforms, etc. The requirements of the API lended itself naturally to the use of a so called REST API, which utilizes the basic HTTP methods of GET, PUT, and DELETE.

GET calls are used to retrieve resources from Bioshare including database records as well as file resources. PUT requests are used to place file resources into Bioshare. DELETE requests are used for deleting file resources from Bioshare (not database records). At this point POST is not used, as the API is not intended for inputting data into the database.

This method was chosen over one like SOAP or XML-RPC due to its relative simplicity. Complex data was not required in either the request or the response, which is often the strength of something like SOAP. The result is that we have a more simplistic protocol with as few layers as possible. Additionally, most any client can connect with the standard HTTP methods, whereas a library is needed to use a protocol like SOAP.

All Bioshare REST requests require two cookies to be set in the request. They are the ‘user’ cookie and the ‘password’ cookie. These fields will be omitted from the arguments section of each service, as they are implied here.

user: Set this cookie to the login used for Bioshare’s web interface, ie: joe@ucdavis.edu

pass: Set this cookie to the password associated with the given login. It should be the actual text of the password. Encryption will be taken care of by the SSL connection.

SERVICES

Connect Service

Description: This service is the first point of contact that a client will generally make. The client may use this to retrieve information about the services provided by that instance of Bioshare, as well as their locations(when applicable) relative to the root URL.

Query String Arguments: (optional)format- Used to distinguish what format to return data. Current options are “json” and “xml”, and the default is XML.

ie: GET https://bioshare.genomecenter.ucdavis.edu/connect.php?format=xml Response: (example in XML)

<info>
	<system>
		<url>http://biosharedev.genomecenter.ucdavis.edu</url>
	</system> 
	<user>
		<login>amschaal@ucdavis.edu</login>
		<first_name>Adam</first_name>
		<last_name>Schaal</last_name>
	</user>
	<services>
		<get>1</get>
		<put>1</put>
		<delete>1</delete>
		<get_projects>/getProjects.php</get_projects>
		<get_sub_projects>/getSubProjects.php</get_sub_projects>
		<directory_listing>/listDir.php</directory_listing>
	</services>
</info>

Get Projects Service

Description: This is likely the first service call an application would make after retrieving info from the Connect Service. This call retrieves the projects that the given user has access to.

Query String Arguments: (optional)format- Used to distinguish what format to return data. Current options are “json” and “xml”, and the default is XML.

ie: GET https://bioshare.genomecenter.ucdavis.edu/getProjects.php?format=xml

Response: (example in XML)

<projects>
	<project>
		<id>7</id>
		<submitted>2008-06-17 16:43:53</submitted>
		<group>Tsutsui</group>
		<title>Ant 454 SNP Discovery</title>
		<description>SNP discovery based on 454 sequencing...</description>
	</project>
	<project>
		<id>9</id>
		<submitted>2008-06-30 15:14:30</submitted>
		<group>Loge, Frank</group>
		<title>Salmon VH family classficiation</title>
		<description>Classify Salmon family based on the VH sequences</description>
	</project>
	<project>
		<id>10</id>
		<submitted>2008-06-30 15:55:49</submitted>
		<group>Dandekar</group>
		<title>Pavan Kumar miRNA tiling array</title>
		<description>detection of micro RNA via a custom tiling array, using genepix reader data</description>
	</project>
</projects>

Get Sub Projects Service

Description: Once the application has retrieved information regarding projects, they will generally want to request information about sub projects. This call will retrieve any sub projects that the authenticated user has access to for a given project.

Query String Arguments: projectID- The database ID of the project as supplied from the Get Projects Service (optional)format- Used to distinguish what format to return data. Current options are “json” and “xml”, and the default is XML.

ie: GET https://bioshare.genomecenter.ucdavis.edu/getSubProjects.php?projectID=13&format=xml

Response: (example in XML)

<sub_projects>
	<sub_project>
		<id>18</id>
		<submitted>2008-07-07</submitted>
		<description>ISMB Panel discussion on "best practice on building and managing a Bioinformatics Core"</description>
		<data_URL>http://biosharedev.genomecenter.ucdavis.edu/Data/socdkosdhd/</data_URL>
		<type>Presentation</type>
	</sub_project>
	<sub_project>
		<id>29</id>
		<submitted>2008-07-11</submitted>
		<description></description>
		<data_URL>http://biosharedev.genomecenter.ucdavis.edu/Data/s9dxcf0kks2/</data_URL>
		<type>Protein family classification</type>
	</sub_project>
</sub_projects>

Get Directory Content Service

Description: The application may request a list of files and folders within any of the data directories on Bioshare, assuming that the authenticated user is authorized to see those files/folders.

Query String Arguments: directory- A string indicating the full URL of the directory, or the portion after the root website URL, i.e. /Data/sdf89sd0f0/ Also, please note that the trailing slash is required (optional)format- Used to distinguish what format to return data. Current options are “json” and “xml”, and the default is XML.

ie: GET http://bioshare.genomecenter.ucdavis.edu/listDir.php?directory=/Data/sodifjdsld/&format=xml

Response: (example in XML)

<listing URL="http://biosharedev.genomecenter.ucdavis.edu/Data/sodifjdsld/">
	<directory>folder1</directory>
	<directory>folder2</directory>
	<file>
		<name>result.png</name>
	</file>
	<file>
		<name>ouput.txt</name>
	</file>
	<file>
		<name>summary.htm</name>
	</file>
	<file>
		<name>sequence.txt</name>
	</file>
</listing>

Get File Service

Description: The most standard service which simply does what your web browser does when you enter a URL into it. It returns the content at that location. In this context it is used to retrieve a file at a known location. Note, that this service does not actually require the “user” and “pass” cookies, as data is secured by use of a secret string in the URL.

Arguments: NONE

ie: GET http://bioshare.genomecenter.ucdavis.edu/Data/sodifjdsld/someFile.txt

Response: 

The contents of the file.

Put File Service

Description: An application may use this service to upload a file to a given location in the Bioshare repositories. The file will only be uploaded if the authenticated user has permission to upload to that particular directory.

Arguments: Must stream contents of file that should be uploaded to the given location.

ie: PUT https://bioshare.genomecenter.ucdavis.edu/Data/sodifjdsld/someFile.txt

Response: None, other than the HTTP status code

Delete File Service

Description: An application may use this service to delete a file at a given location in the Bioshare repositories. The file will only be deleted if the authenticated user has permission to delete files within that directory.

Arguments: No additional arguments

ie: DELETE https://bioshare.genomecenter.ucdavis.edu/Data/sodifjdsld/someFile.txt

Response: None, other than the HTTP status code