NAV

Lotus Base API v1

shell javascript

Introduction

The Lotus Base API is a RESTful service powered by Slim. Our API offers predictable, resource-oriented URLs that return appropriate HTTP status codes to indicate the outcome of an API call. The latest version of our API is v1.

The API endpoint is available at https://lotus.au.dk/api/v{{version}}. The most current API endpoint is at https://lotus.au.dk/api/v1.

The format returned is JSON, in the following format:

{
    "status": "HTTP_STATUS_CODE",
    "data": "DATA_OBJECT",
    "message": "OPTIONAL_MESSAGE_FROM_API",
    "more_info": "OPTIONAL_URL_FOR_FURTHER_INFO"
}

We use a universally interchangeable format known as JavaScript Object Notation (JSON) to transmit data from our API to your end-point. Even though the HTTP status code is included in the response header, we also include it as part of the JSON returned. Note that all the data request will be returned in the nested data object.

Under most conditions, the message object will be empty unless an HTTP error code is provided. The message can be either utilized by developers to troubleshoot erroneous API calls, or used to inform your users about any issues occuring in the backend. Occasionally, a more_info key is provided, containing a documentation reference where you may glean further information on the reason of the error message you are receiving.

If you encounter any issue with using our API, please do not hestitate to contact us through various channels: open an issue with our GitHub project, reach out to us via @LotusBase, or drop us an email.

API key / access token

To authorize, please include your custom API key with each request:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "X-API-KEY: {{ YOUR_API_KEY }}"
// Set custom headers for all API calls using a global AJAX prefilter
$.ajaxPrefilter(function(options) {
  if (!options.beforeSend) {
    options.beforeSend = function (xhr) { 
      xhr.setRequestHeader('X-API-KEY', YOUR_API_KEY);
    };
  }
});

// Manually add access token to requests
$.ajax({
  url: 'https://lotus.au.dk/api/v1/',
  type: 'GET',
  data: {
    key1: value1,
    key2: value2,
    access_token: YOUR_API_KEY
  }
})

Lotus Base uses API keys to allow access to the API. Please register a new API key at our developer portal before proceeding. We do not restrict API keys to individual domains. If you suspect that your API key is being misused or abused, you can revoke it at any time and create a new one. The API expects this generated key to be included in all API requests to the server in one of the many following formats:

Lotus BLAST

Sequence retrieval

Get/blast/{db}/{id}

Retrieves the sequence based on an identifier found in a valid BLAST database. This method calls the blastdbcmd method of NCBI BLAST+ package internally. Note that this method requires URL parameters db and id to be defined, with optional parameters specified as GET query string.

Example query and response received for the gene LjFls2 (Lotus homolog of the Arabidopsis * flagellin-sensing 2 gene, *AtFLS2), to retrieve the amino acid sequence from the L. japonicus MG20 proteins v3.0 BLAST database. Note that the amino acid sequence returned, as seen below, has been truncated for brevity.

curl "https://lotus.au.dk/api/v1/blast/20130521_Lj30_proteins.fa/Lj4g3v0281040.1"
$.ajax({
  url: 'https://lotus.au.dk/api/v1/blast/20130521_Lj30_proteins.fa/Lj4g3v0281040.1',
  type: 'GET'
})
{
  "status": 200,
  "data": {
    "success": true,
    "fasta": [
      {
        "id": "Lj4g3v0281040.1",
        "sequence": "MLSLKFSLTL ... SALMKLQTEK",
        "header": "lcl|Lj4g3v0281040.1 Flagellin-sensing 2-like protein OS=Lotus japonicus PE=4 SV=1,100,0,LRR_8,NULL; PROTEIN_KINASE_ST,Serine/threonine-protein kinase, active site; LRR_1,Leucine-rich repea|CUFF.46782.1"
      }
    ]
  }
}

Example query and response, same as above, but now with additional and optional GET query parameters, with the intention to truncate the amino acid sequence to the first 10.

curl "https://lotus.au.dk/api/v1/blast/20130521_Lj30_proteins.fa/Lj4g3v0281040.1?from=1&to=10"
$.ajax({
  url: 'https://lotus.au.dk/api/v1/blast/20130521_Lj30_proteins.fa/Lj4g3v0281040.1?from=1&to=10',
  type: 'GET'
})
{
  "status": 200,
  "data": {
    "success": true,
    "fasta": [
      {
        "id": "Lj4g3v0281040.1",
        "sequence": "MLSLKFSLTLVIVFSIVASV",
        "header": "lcl|Lj4g3v0281040.1:1-20 Flagellin-sensing 2-like protein OS=Lotus japonicus PE=4 SV=1,100,0,LRR_8,NULL; PROTEIN_KINASE_ST,Serine/threonine-protein kinase, active site; LRR_1,Leucine-rich repea|CUFF.46782.1"
      }
    ]
  }
}

Query parameters

URL parameter Description
db Required. A valid BLAST database hosted with Lotus Base. See here for the full list of BLAST databases available.
id Required. The identifier of an entry in the relevant BLAST database.
GET parameter Description
strand The strand of the sequence to retrieve. Coerced to minus when from and to coordinates are flipped (see below).
from Starting position of the sequence to truncate. If set to 0, this parameter will be ignored.
to Ending position of the sequence to truncate. If set to 0, this parameter will be ignored.
download Boolean parameter. When specified, the script will generate a FASTA file that will be downloaded. No JSON response will be returned.

Important notes

LORE1 mutant population

Get all LORE1 lines

Get/lore1

An example of a returned JSON, with the first three elements shown:

[
  "30000001",
  "30000002",
  "30000003",
]

Returns all distinct Danish LORE1 mutant line IDs that can be ordered, and that we have seed stocks of—a ballpark figure of 100,000+ lines. This will generate a large JSON file, so you might want to stream the response instead.

LORE1 line IDs are identified internally using the following regex pattern: ^3\d{7}. Therefore, IDs like 30000001 are accepted, but not DK01-030000001.

For an overview of the current LORE1 collection available, please refer to the LORE1 resource page.

Verify LORE1 lines

Get/lore1/{pids}/verify

Request and response example for a valid lines 30000001, 30000002, and 30000003:

curl "https://lotus.au.dk/api/v1/lore1/30000001,30000002,30000003/verify"
$.ajax({
  url: 'https://lotus.au.dk/api/v1/lore1/30000001,30000002,30000003/verify',
  type: 'GET'
})
{
  "status": 200,
  "data": {
    "pid_found": [
      "30000001",
      "30000002",
      "30000003"
    ]
  }
}

Request and response example for invalid lines, 20000001, 30000000, DK-030000001:

curl "https://lotus.au.dk/api/v1/lore1/20000001,30000000,DK-030000001/verify"
$.ajax({
  url: 'https://lotus.au.dk/api/v1/lore1/20000001,30000000,DK-030000001/verify',
  type: 'GET'
})
{
  "status": 404,
  "message": "No valid plant ID has been found.",
  "data": {
    "pid_invalid": [
      "20000001",
      "DK-030000001"
    ],
    "pid_notFound": [
      "30000000"
    ]
  },
  "more_info": "https://lotus.au.dk/docs/api/v1#404-not-found"
}

Request and esponse example for partially invalid request. Here we used a valid line, 30000001 and a non-existent line, 30000000:

curl "https://lotus.au.dk/api/v1/lore1/30000001,30000000/verify"
$.ajax({
  url: 'https://lotus.au.dk/api/v1/lore1/30000001,30000000/verify',
  type: 'GET'
})
{
  "status": 207,
  "message": "One or more plant ID you have provided are not available for ordering.",
  "data": {
    "pid_notFound": [
      "30000000"
    ],
    "pid_found": [
      "30000001"
    ]
  },
  "more_info": "https://lotus.au.dk/docs/api/v1#207-partial-success"
}

Performs validation of a list of LORE1 mutant line IDs. A line is considered “valid” as long as it:

  1. exists in the LORE1 collection,
  2. has seeds available for shipping, and
  3. is flagged as orderable in our database.

LORE1 mutant line ID formats

On the server side, a simple regex-based validation is used to check for the validity of a line ID. The pattern used is ^3\d{7}$, which means the line ID must start with the number 3, followed by seven numerical characters. An example of a valid line ID is 30000001. We do not support querying for line IDs in the format of DK{batch}-0{line_id}, for example, DK01-030000001, because the country of origin and batch are redundant information.

The following table summarizes how mutant line IDs are treated:

Line Description
30000001 Valid line, will be passed into prepared statement for querying. Appended to the pid_found array in returned data.
39999999 Valid line, but does not exist in the database. Appended to the pid_notFound array in returned data.
20000001 Invalid line, as all LORE1 lines are identified with an eight-digit character starting with 3. Appended to the pid_invalid array in returned data.
DK‑030000001 Invalid line, as all LORE1 lines are identified with an eight-digit character starting with 3. Appended to the pid_invalid array in returned data.

Query parameters

Parameter Description
pids Required. This should be a list of LORE1 mutant line IDs separated by the following: a comma, space, or linebreak.

Responses

Due to the nature of the request, the list provided to the API may contain a mixture of valid and invalid lines. Therefore, we issue a 207 response in the event that some of the lines in the list are valid.

Response Description
200 All IDs provided are available for ordering and valid
207 Some IDs provided are available for ordering and valid
404 All IDs provided are invalid

Retrieve LORE1 flanking sequences

Get/lore1/flanking-sequence/v{version}/{id}[/{cutoff}]

Request and response example for requesting the flanking sequence of the insertion, identified with the md5 hash 7cd0a4c8e9f10c4096d1782702267c59. The flanking sequence is the response shown below has been truncated for brevity.

curl "https://lotus.au.dk/api/v1/lore1/flanking-sequence/v3.0/7cd0a4c8e9f10c4096d1782702267c59"
$.ajax({
  url: 'https://lotus.au.dk/api/v1/lore1/flanking-sequence/v3.0/7cd0a4c8e9f10c4096d1782702267c59',
  type: 'GET'
})
{
  "status": 200,
  "data": {
    "insFlank": "TGTTTTCACC ... TTATATCTCT",
    "cutoff": false,
    "plantID": "30000001",
    "chromosome": "chr0",
    "position": "146086605",
    "orientation": "F"
  }
}

Gets the flanking sequence of a LORE1 insertion, identified by its md5 hash. The md5 hash of each line is computed from the following information: plant ID, Chromosome, Position, Orientation, Version

Query parameters

Parameter Description
version Required. This should be a valid Lotus genome version
id Required. A 32-character hexademical identifier of a LORE1 line
cutoff The cutoff, in base pairs, from the insertion site. The default cutoff value is 1000, which is the maximum extent of the flanking sequence

Retrieve LORE1 order statistics

Get publicly available statistics for LORE1 orders from Lotus Base.

By country

Get/lore1/orders/all/by-country

Truncated response:

{
  "data": [
    {
      "countryCode": "ABW",
      "countryName": "Aruba",
      "orderCount": 0
    },
    {
      "countryCode": "AFG",
      "countryName": "Afghanistan",
      "orderCount": 0
    }
  ]
}

Returns all LORE1 order counts mapped to the three-letter country code, as defined by ISO-3166-1 alpha3, and the full country name. Each country is an element in the array returned, containing the following information:

HTTP Status Codes

Lotus Base API returns the following HTTP status codes:

Status Meaning
200 OK
207 Partial Success—Part of the request is valid. Invalid data requires attention.
400 Bad Request—Request is malformed, or required data is not provided.
401 Unauthorized—Invalid API token.
403 Forbidden—Insufficient privilege, or lack of authentication.
404 Not Found—The resources you have requested for are unavailable.
405 Method Not Allowed—You tried to access the API with an invalid method.
500 Internal Server Error—We had a problem with our server. Try again later.
503 Service Unavailable—We’re temporarially offline for maintanance. Please try again later.

Error messages

Invalid Lotus genome version

We currently host the following versions of the Lotus genome: v2.5 and v3.0. Versions should be provided without the v prefix. This error is generated when the genome version provided does not match any entires in the aforementioned list.

PDO Exception

This is typically returned as a 500 status. It indicates that the server has encountered an internal error, suggesting that an exception flag has been raised by PDO, a driver used to interface with our MySQL databases.