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:
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:
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/genome/?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=22>; rel="last" Vary: Accept X-Total-Count: 2198
HTTP status codes
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