REST API for the OMA Browser

The OMA Brower now supports its own REST API, which serves as a window into its database. It enables the abstraction of OMA browser’s data which also allows it to be more accessible via other programming languages. Furthermore, due to its RESTful architecture, it allows the users to access the data they need easily through HTTP requests sent to the server which can be found at:

http://omabrowser.org/api

The OMA REST API supports many data formats and its predominant use of the JSON data format makes it very browser-compatible.To further facilitate the ease of access, we have also developed a Python library and R package to serve as user friendly wrappers around the API. The links to their documentation can be found below:

  • R package: {linktocome}
  • Python library: {linktocome}

Pagination in the API

Note that some endpoints, such as the list of all Hierarchical Orthologous groups, return a very long list. In order to keep the response size and time manageable the API will take advantage of pagination, which is a mechanism for returning a subset of the results for a request (by default, we return the results in chunks of 100 objects) and allowing for subsequent requests to “page” through the rest of the results until the end is reached. This pagination is implemented with a "page" query parameter and a "per_page" parameter to specify the number of objects per page.

Information about pagination is provided in the Link header of an API call. This is a popular way how to implement pagination for APIs. In essence this strategy includes in the HTTP reply header a "Link" header with the urls to to next, previous, first and last page. Furthermore, we include in the "X-Total-Count" header the total number of objects that the request will return over all pages. Here is an example request:

curl -I "https://omabrowser.org/api/genomes/?page=2"
HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Link: 
 <https://omabrowser.org/api/genomes/>; rel="first",
 <https://omabrowser.org/api/genomes/>; rel="prev",
 <https://omabrowser.org/api/genomes/?page=3>; rel="next",
 <https://omabrowser.org/api/genomes/?page=64>; rel="last"
Vary: Accept
X-Total-Count: 2085

HTTP status codes

Status Code Description
200 OK. All is well.
400Malformed request.
404 Not found.
500 Internal Server Error.

Available API Endpoints

Below we list all the available endpoints together with a brief description of what they return and the parameters they take.

# Install the command line client
$ pip install coreapi-cli
# Install the Python client library
$ pip install coreapi
<!-- Load the JavaScript client library -->
<script src="/static/rest_framework/js/coreapi-0.1.1.js"></script>
<script src="/api/docsschema.js"></script>

function

genome

group

hog

pairs

protein

sequence

taxonomy

version

xref