The information and links on this page are no longer being updated and are provided for reference purposes only.
A REST (Representational State Transfer) API is provided "out of the box" for all caCORE SDK-generated systems, like caBIO. It's possible to leverage this API from client-side Ajax components and provide easy access to caBIO data without writing any server-side code. This page explains how to use Ajax to query the caBIO REST API, for those already familiar with the concepts. For a gentler introduction, please see the Ajax REST Hack-a-thon.
What is Ajax?
You can learn more about Ajax on the web:
Querying the REST API
The REST API is queried by a URL with a specific format:
For example, to query caBIO for Gene which have the symbol "brca1", the URL is constructed as follows:
Requesting this URL will return an XML document containing the result objects. Constructing simple queries is easy to do with the caBIO Home Page's query interface.
- Click on "Continue" and then select a criteria class from the Domain Class Browser.
- Enter criteria in the text boxes which appear on the right
- Select a target class by using the "Search Object" drop down menu
- Hit Submit to get results in HTML format
- Change the "GetHTML" part of the URL to read "GetXML" to get results in XML format
Constructing more advanced queries such as nested queries can also be accomplished with this API. For more information please see the caBIO Technical Guide.
Using jQuery to connect to caBIO
We call jQuery's ajax() method and give it a few parameters:
- type - Always send a GET request when querying the REST API (as opposed to a POST request).
- url - The base URL of the REST API (see below for caveats!)
- data - The query string specifying the actual query. Here we're querying for brca1 genes and then returning their associated microarray reporters.
- dataType - The REST API will return XML. We specify it here so that jQuery parses it for us.
- success - A callback function that is executed when the results are ready.
The success callback is an anonymous function which is called by jQuery when the results are available. The
xml parameter will allow access to the parsed results, which you can see here. In this case, we are searching the results for
<class> nodes which are children of
<queryResponse> nodes. Then for each
<class> node, we take the child node named
<field name="name"> and extract the value of that node, which happens to be the reporter name. We then add that reporter name to the result list, as a list item (
Creating a REST Proxy
We saw earlier that the query URL provided to jQuery does NOT include the hostname of the caBIO server. This is actually the result of a security precaution taken by most web browsers, which limits Ajax requests to the same server as the one serving the page. Therefore, you can query your own local REST API, but not caBIO. However, there is a simple workaround which just involves installing a proxy on your local server to forward requests to caBIO. The proxy can be written in any language, or even implementing using something like Apache URL Rewriting. Our example consists of a tiny CGI script in Python.
How it works
- The user requests your page, and your server provides it
- When the Ajax query is triggered, it connects to your server, to a proxy. For example, the URL might be /cgi-bin/proxy.py if you install the Python proxy script.
- The proxy script forwards the request to caBIO and receives the results.
- Your server responds to the Ajax query with the results provides by caBIO.
- caBIO Live Ajax Demos
- Ajax with REST Hack-a-thon Tutorial
- Ajax with REST Presentation at the 2008 caBIG Annual Meeting
- caBIO Technical Guide and Javadocs
Help Downloading Files
For help accessing PDF, RTF, MS Word, Excel, PowerPoint, audio, or video files on this wiki, go to Help Downloading Files.