Using the API

Besides our web service for searching, retrieving, and exporting data we also provide an API interface to, for example, automate workflows that require obtaining certain tRNA sequences. In order to keep our service responsive and fair, we limit API requests to 1 request per second per client. Note that repeatedly violating this limit might result in a temporary lock-out from the tRNAdb service. Please ensure your use of the API respects these limits (for example, via waiting/sleep after every request).

Querying the API

The API provides nearly equal search parameters as the Search form and can be reached with POST request at https://www.tdb.bioinf.uni-leipzig.de/api.

A POST request with JSON content-type is expected. The following JSON contains all supported fields, and field types:

{
    'database': <list, string>, 
    'organism': <list, string>,
    'clade': <list, string>,
    'ncbi_id': <string, integer, list>'
    'amino_acid': <list, string>,
    'anticodon': <list, string>, 
    'sequence': <dictionary {'0': <string>, '1': <string>, ..., '16': <string>}, string>,
    'structure': <dictionary {'0': <string>, '1': <string>, ... , '16': <string>}, string>, 
    'reference': <string>, 
    'trna_id': <list, string>,
    'id': <list, integer> 
    'sprinzl_id': <list, string>, 
    'page_size': <integer>,
    'page_offset': <integer>
}

In particular, you need to pay attention to the 'page_offset' and 'page_size' parameters. If you do not specify these two, the API will always return the first (at most) 1000 matching entries. These two parameters are explained in more detail below

Query Parameters

Regions:

For querying sequence and structure we utilize the conserved structural regions of tRNAs. Simply put, they are numbered by occurencce from 5'->3' end of the tRNA. "Empty Regions" in this context are not necessarily empty, but contain nucleotides that do not strictly belong into any of the other structural regions. Indices in the table below are exactly as one would query the API for the 'sequence' and 'structure' fields.

API Response

When you POST a valid JSON to https://www.tdb.bioinf.uni-leipzig.de/api, the server will answer with a JSON in this shape:

{   
        'total_results': <integer>,
        'page_offset': <integer>,
        'page_size': <integer,
        'results': [
                        {<dictionary>},
                        {<dictionary>}, 
                        ... 
                   ]
}

• total_results is an integer value that describes how many tRNAdb entries match the query in total. Note that only up to 1000 entries can be retrieved with a single query.
• 'page_offset' is the page number of results that the 'results' field contains. See "Query Parameters" above for more information.
• 'page_size' is the maximum number of results per page of results retrieved.
• 'results' is a list that contains dictionaries (JSON) of individual entries that match the query.

In case your request JSON was malformed, the server responds with a JSON that describes the error that occured. This JSON could, for example, look something like this: {'error': 'Some fields not supported: some_field'}. If the 'results' list does not contain any entries (or 'total_results is zero), your request does not match any tRNAs in the database.

Entry Fields

Every entry that is returned by the API in the 'results' field is a JSON that contains the following keys/values:

Simple Python Example

Using python for the sake of an easy and readable example, a simple request querying the tRNAdb API for human nuclear Alanine tRNAs could look like this:

import requests
import json

request_dict = {
    "database": "trna",
    "amino_acid": "Ala",
    "organism": "Human",
    "page_size": 1000,
    "page_offset": 0
}


api_server = "https://tdb.bioinf.uni-leipzig.de/api"

api_response = requests.post(
    api_server,
    json=request_dict,
    timeout=10
)

response_data = json.loads(api_response.text)

print()
print("Total results matching query:", response_data["total_results"])

# get the first entry
entry = response_data["results"][0]

print()
print("The first matching entry:")

# output every field name and field data for the first entry
for k in entry.keys():
    print(k,  ":", entry[k])