Using the API

Search Endpoint

• Querying the Search Endpoint
• Search Query Parameters
• API Response
• Response Data Fields
• Example

Export Endpoint

• Querying the Export Endpoint
• Export Query Parameters
• Export Job Lifetime
• Example

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 Search Endpoint

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>,
    'organism_synonym_search': <boolean>
    '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

Search 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 Search 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])

Querying the Export Endpoint

For export of larger (more than 1 000) sets of sequences, we also expose an export endpoint which enables direct export of desired sequences and selected fields to .tsv, .csv, .json, and .fasta. The endpoint can be reached at https://www.tdb.bioinf.uni-leipzig.de/export. The request schema, hence which format the request to https://www.tdb.bioinf.uni-leipzig.de/export should have, is precisely the schema outlined above in the Querying the Search Endpoint but supports additional fields for "filetype", "export_fields", "fasta_identifier".

Export Query Parameters

Export Job Lifetime

After successfully requesting the export job at https://www.tdb.bioinf.uni-leipzig.de/export, the API server responds with a job description in .json format of the shape

{
  "job_id": <string>,
  "status": <string>,
  "total_rows": <integer>,
  "processed_rows": <integer>
}

"job_id" is a unique identifier for your export job. "status" is a current status of the job. An export job moves from "queued" while waiting for execution to "processing" during execution to "done" when execution is finished. "total_rows" is the total number of tRNAdb entries matching your search request. " processed_rows" are already exported/processed rows. Export jobs might take some time, depending on how busy the server is. Jobs might remain in "queued" state for some time.

Status of export jobs can be queried at the https://www.tdb.bioinf.uni-leipzig.de/export/status/<job_id> endpoint for your "job_id". Once the export job is done, hence "status": "done", the exported file can be downloaded at https://www.tdb.bioinf.uni-leipzig.de/export/download/<job_id>. Please note that exported files for finished jobs are deleted after 24 hours.

Simple Export Python Example

Below, there is a simple example python script that creates an export job, saves the job_id, and then queries the status endpoint https://www.tdb.bioinf.uni-leipzig.de/export/status/job_id until the job is done. Finally, it prints the exported file.

import requests
import json
import time

# Export job for genomic human alanine tRNAs
# Export to .json, including the fields
# "trnadb_id", "amino_acid", "anticodon", "taxon_name", "database", "sequence", "version"
request_dict = {
    "database": "trna",
    "amino_acid": "Ala",
    "organism": "Homo sapiens",
    "filetype": "json", 
    "export_fields": ["trnadb_id", "amino_acid", "anticodon", "taxon_name", "database", "sequence", "version"] 
}

# Endpoint for starting export jobs
export_endpoint = "https://www.tdb.bioinf.uni-leipzig.de/export"

# Request send to export endpoint, with a 10s timeout
api_response = requests.post(
    export_endpoint,
    json=request_dict,
    timeout=10
)

# Read server response. If an error occured, response will contain "error" field with a description.
response_data = json.loads(api_response.text)

# Get the job ID assigned to export job
job_id = response_data["job_id"]
print("Export Job with ID:", job_id)

# Endpoint to query status of export job
status_path = "https://www.tdb.bioinf.uni-leipzig.de/export/status/" + job_id

# While the export job is not "done"
while response_data["status"] != "done":

    # Get updated status of export job
    print()
    api_response = requests.get(
        status_path,
        timeout=10
    )

    # Read status response
    response_data = json.loads(api_response.text)

    # If export job not finished, output progress
    if response_data["status"] != "done":
        print("Job status", response_data["status"])
        print("Job ID", job_id)
        print("Job progress", response_data["progress"], "/", response_data["total_rows"])
        time.sleep(1)

    # If export job is finished, output exported data
    else:
        print("Job finished. Download available at", "https://www.tdb.bioinf.uni-leipzig.de" + response_data["download_url"])
        export_data = requests.get("https://www.tdb.bioinf.uni-leipzig.de" + response_data["download_url"], stream=True)
        print("Export job contents:")
        print(export_data.text)