API overview

Most data in RNAcentral can be accessed programmatically using a RESTful API allowing for integration with other resources. The API implementation is based on the Django Rest Framework.

Web browsable API

The RNAcentral API is web browsable, which means that:

  • the data is served in either human- or computer-friendly formats depending on whether a URL is viewed in a browser or is retrieved programmatically

  • many resources are hyperlinked so that it's possible to navigate the API in the browser.

As a result, developers can familiarise themselves with the API and get a better sense of the RNAcentral data.

Browse the API

Versioning

To ensure that changes in the RNAcentral API don't break the applications relying on it, the API is versioned, and the version is included in the API's URL.

For example, the current API is at Version 1 and is available at https://www.rnacentral.org/api/v1, and the next version will be available at https://www.rnacentral.org/api/v2.

The latest version of the API can be accessed at https://www.rnacentral.org/api/current, but it's not recommended to use this endpoint for long-term development as the underlying data model may change.

No backward-incompatible changes are made to each version after it's been made public. More specifically, it's guaranteed that within one version there will be no:

  • changing urls
  • deleting or renaming data fields
  • changing data field types

The following non-disruptive changes may be implemented to a public API:

  • adding new endpoints
  • adding new data fields
  • adding new filtering methods

An advance notice will be given before obsoleting an API version. To stay up to date, please consider signing up for the RNAcentral updates.

Throttling

The maximum number of requests from the same IP address is limited to 20 requests per second. Currently there is no limit on the total number of requests from the same IP.

The limit can be lifted for registered users, so please get in touch if you require a higher request rate.

API v1 documentation

Example responses

Responses containing multiple entries have the following fields:

  • next and previous are urls to the corresponding results page
  • results is an array of entries.

Example

https://www.rnacentral.org/api/v1/rna/
{
    "next": "https://www.rnacentral.org/api/v1/rna/?page=2",
    "previous": null,
    "results": [
        {
            "url": "https://www.rnacentral.org/api/v1/rna/URS0000000001",
            "rnacentral_id": "URS0000000001",
            "md5": "06808191a979cc0b933265d9a9c213fd",
            "sequence": "CUGAAUAAAUAAGGUAUCUUAUAUCUUUUAAUUAACAGUUAAACGCUUCCAUAAAGCUUUUAUCCA",
            "length": 66,
            "xrefs": "https://www.rnacentral.org/api/v1/rna/URS0000000001/xrefs"
        },

        // 9 more entries
    ]
}

Responses containing just a single entry don't have the extra navigation fields:

https://www.rnacentral.org/api/v1/rna/URS0000000001
{
    "url": "https://www.rnacentral.org/api/v1/rna/URS0000000001",
    "rnacentral_id": "URS0000000001",
    "md5": "06808191a979cc0b933265d9a9c213fd",
    "sequence": "CUGAAUAAAUAAGGUAUCUUAUAUCUUUUAAUUAACAGUUAAACGCUUCCAUAAAGCUUUUAUCCA",
    "length": 66,
    "xrefs": "https://www.rnacentral.org/api/v1/rna/URS0000000001/xrefs"
}

Hyperlinked vs flat responses

Some objects are represented by hyperlinks, for example in the default RNA object cross-references are represented by a hyperlink:

"xrefs": "https://www.rnacentral.org/api/v1/rna/URS0000000001/xrefs/"

Sometimes it is desirable to retrieve all nested objects in a single request, which can be done using the flat=true url parameter. Note that such requests may take longer.

Examples

Pagination

Responses containing multiple entries are paginated to prevent accidental downloads of large amounts of data and to speed up the API.

To navigate between pages, specify the page parameter.

The page size is controlled by the page_size parameter. Its default value is 10 entries per page, and the maximum number of entries per page is 100.

Examples

Output formats

The following output formats are supported for all endpoints: JSON, JSONP (for cross-origin Javascript requests), YAML, HTML.

In addition, the data for individual RNA sequences can be downloaded in FASTA format.

There are three ways of specifying the format:

  1. format url parameter

  2. .format suffix

  3. Accept headers

    curl -H "Accept: application/json" https://www.rnacentral.org/api/v1/rna/URS0000000001
curl -H "Accept: text/fasta" https://www.rnacentral.org/api/v1/rna/URS0000000001
curl -H "Accept: application/yaml" https://www.rnacentral.org/api/v1/rna/URS0000000001
curl -H "Accept: text/html" https://www.rnacentral.org/api/v1/rna/URS0000000001

In case there is a conflict between the Accept headers and the format parameter, an error message is returned, for example:

curl -H "Accept: application/json" https://www.rnacentral.org/api/v1/?format=yaml
or
curl -H "Accept: application/yaml" http://127.0.0.1:8000/api/v1/?format=json
{
  "detail": "Could not satisfy the request's Accept header"
}

Filtering

The API supports several filtering operations that complement the main RNAcentral search functionality.

Filtering by sequence length

There are 3 url parameters: length, min_length (greater or equal length), and max_length (less or equal length).

Examples

Filtering by external ids

The external id is an id assigned to a sequence in one of the Expert Databases, which is imported into RNAcentral as a cross-reference.

The external id can be specified by setting the external_id url parameter.

Examples

Combined filters

Any filters can be combined to narrow down the query using the & symbol as a separator, which acts as the logical AND operator. More logical operators will be supported in the future.

Example

Genome annotations

The API provides an endpoint for retrieving annotations based on genomic coordinates for a number of species.

The response content is similar to that provided by the Ensembl REST API and can be directly used to visualise the data using the Genoverse HTML5 genome browser.

The genome location should be in the chromosome:start-end format and may contain optional commas.

Examples

Example script

A common task is finding whether some sequence of interest has an RNAcentral id.

An example Python script for looking up RNAcentral unique sequence ids (URS) is provided and can be used in more complicated programs.

Instead of sending the entire sequence over the network to the RNAcentral servers, the script only submits the md5 value calculated based on the sequence. The md5 value is 32 characters long and is unique for each sequence. Using md5 saves traffic and decreases the response time.

Internally RNAcentral uses the Digest::MD5 Perl module for computing the md5 values. Additional notes:

  • all sequences are uppercase
  • md5 is computed for DNA sequences (so all U's should be replaced with T's).

Cross domain requests

To use the API in a javascript application, please use jsonp requests.

Example using jQuery 

$.ajax({
    url: 'https://www.rnacentral.org/api/v1/rna/URS0000000001?format=jsonp',
    dataType: 'jsonp',
    jsonp: false,
    jsonpCallback: 'callback',
    success: function(data){
        // do something with the data
        console.log(data.rnacentral_id + ', ' + data.sequence);
    },
});

Trailing slash

The trailing slash in all urls used in the API is optional.

Examples

These requests should return the same results, both in the browser and when retrieved programmatically:

Improve this page