Skip Navigation
NIH | National Cancer Institute | NCI Wiki   New Account Help Tips
Child pages
  • caBIO REST API with Ajax
Skip to end of metadata
Go to start of metadata

The information and links on this page are no longer being updated and are provided for reference purposes only.

Contents of this Page

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?

Ajax stands for "Asynchronous Javascript and XML" and is a technique for creating interactive web applications. Ajax allows web pages to be updated without page reloads. Gmail and Google Maps are popular examples of Ajax technology.

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:

http://server/app/GetXML?query=TargetObject&CriteriaObject[&attribute=value]

For example, to query caBIO for Gene which have the symbol "brca1", the URL is constructed as follows:

http://cabioapi.nci.nih.gov/cabio41/GetXML?query=Gene&Gene[@symbol=brca1]

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.

  1. Click on "Continue" and then select a criteria class from the Domain Class Browser.
  2. Enter criteria in the text boxes which appear on the right
  3. Select a target class by using the "Search Object" drop down menu
  4. Hit Submit to get results in HTML format
  5. 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

You can use any Javascript library, or even plain Javascript to construct an Ajax query to the caBIO REST API. We will use the popular jQuery library as an example. Let's look at the first example form the caBIO Ajax Examples page.

Javascript
jQuery.ajax({
    type: "GET",
    url: "/cabio41/GetXML",
    data: "query=ExpressionArrayReporter&Gene[@symbol=brca1]",
    dataType: "xml",
    success: function(xml) {
        nodes = jQuery("queryResponse>class", xml)
        nodes.each(function() {
            reporter = $('field[name="name"]', this).text();
            jQuery("#results").append("<li>"+reporter+"</li>")
        })
    }
})

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 (<li>).

More information about jQuery is available in their excellent documentation and tutorials

Exit Disclaimer logo

.

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.

Example CGI proxy script written in Python
#!/usr/bin/env python
import os
import urllib
url = 'http://cabioapi.nci.nih.gov/cabio41/GetXML?'
qs = os.environ["QUERY_STRING"]
r = urllib.urlopen(url+qs).read()
print "Content-type: text/xml\n\n%s"%r

Proxy Architecture

proxy architecture diagram

How it works

  1. The user requests your page, and your server provides it
  2. 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.
  3. The proxy script forwards the request to caBIO and receives the results.
  4. Your server responds to the Ajax query with the results provides by caBIO.

References

Help Downloading Files

For help accessing PDF, RTF, MS Word, Excel, PowerPoint, audio, or video files on this wiki, go to Help Downloading Files.

  • No labels