WABI BLAST Details

URI POST /blast (submit a search job)

This method appends a BLAST search to the job queue and returns the Request ID.
The BLAST search criteria, method for notifying the result, and other options are specified using HTTP parameters.

Item Description
HTTP Method POST
URI /blast
HTTP Parameters querySequence Search sequence data in multi-FASTA format
example:
>my query sequence 1
CACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA
GCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG
GTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC

Note: Increasing the number of sequences will not increase the degree of parallel processing.
We recommend reducing the number of sequences searched for the web API, as this will better balance the load on the job management engine.
datasets Dataset (example: "ddbjall")
database Database (example: "hum", "hum pri")
program BLAST program (example: "blastn")
parameters Other options (example: "-v 100 -b 100 -e 10 -F F -W 11")
format response data format (example: "text", "json")
result result retrieval method (example: "www", "mail")
address Email address
Request action Add a new BLAST search job to the queue for processing.
HTTP Response If successful Submit job information including Request ID
If failed HTTP status 4xx

Server-side processing flow

  1. Check validity of input values.
    If an invalid input value is found, then the processing is interrupted and HTTP status 400 Bad Request is returned.
  2. Add the BLAST search into the job queue.
  3. Information about the job added to the queue is returned using the specified format.
    If the specified format is not available, then HTTP status 400 Not Found is returned.

Input validation check performed

datasets (optional)
  1. Causes an input validation error if an undefined value is specified.
    Note:Currently not used. Consistency check between the database is not performed.
database
  1. Required value.
  2. Database names must be separated by spaces; otherwise, the check will cause an input validation error. Database names must comprise only alphabets and underscore "_".
    example: "hum""hum pri" など。
program
  1. Required value.
  2. Causes an input validation error if an undefined value is specified.
format
  1. Required value.
  2. Causes an input validation error if an undefined value is specified.
parameters (optional)
  1. Causes an input validation error unless options and corresponding values are listed using space as separators.
  2. Causes an input validation error if invalid options are specified. A valid option depends on the specified program, as follows:
    • In case program value is "megablast":
      Options must be one or more of ADEFGHIJLMNPRSTUVWXYZbefglmnpqrstvyz; other options will cause an input validation error.
      example: "-A" is a valid option, but "-B" will cause an input validation error.
    • For all other program values:
      Options must be one or more of ABCDEFGIJKLMPQSTUVWXYZbefglmnqrstvwyz; other options will cause an input validation error.
      example: "-B" is a valid option, but "-H" will cause an input validation error.
  3. Option values can be a numeric value, alphanumeric characters, or comma-separated alphanumeric characters.
    example: "-1", "foo,bar", etc.
result
  1. Required value.
  2. Causes an input validation error if an undefined value is specified.
address
  1. Requires value if the value of result is "mail".
  2. Only a valid email address is permitted. Other values will cause an input validation error.

Response data

In the case of successful completion:

A “successful” HTTP status code such as 200 will be returned.
The field requestId will contain Request ID
Other values such as current-time and other request information may be included in the response data; however, formatting of these values may change in the future.
Please use the HTTP status code to determine the success or failure of the request.
In the case of failed completion:
A “client error” HTTP status code such as 400 will be returned.
The key called error-messages included in the returned data will contain an error message indicating information such as the name of the parameter that caused input validation error.
Other values including the cause of the error and other request information may be included in the returned data; however, formatting of these values may change in the future.
Please use the HTTP status code to determine the success or failure of the request.

Example request and response

Examples of input data
HTTP Parameter Input Value
address ""
database "hum"
datasets "ddbjall"
format "json"
parameters " -v 100 -b 100 -e 10 -F F -W 11"
program "blastn"
querySequence >my query sequence 1
CACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA
GCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG
GTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC
result "www"
Example response for a successfully completed request
HTTP Status 200
 1{
 2        "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
 3        "program": "blastn",
 4        "datasets": "ddbjall",
 5        "database": "hum",
 6        "parameters": " -v 100 -b 100 -e 10 -F F -W 11 ",
 7        "current-time": "2013-01-01 12:34:56",
 8        "start-time": "",
 9        "current-state": "" 
10}
HTTP Status 200
 1<?xml version="1.0" ?>
 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 3<result>
 4  <requestId>wabi_blast_1111-1111-1111-11-111-111111</requestId>
 5  <program>blastn</program>
 6  <datasets>ddbjall</datasets>
 7  <database>hum</database>
 8  <parameters> -v 100 -b 100 -e 10 -F F -W 11 </parameters>
 9  <current-time>2013-01-01 12:34:56</current-time>
10  <start-time></start-time>
11  <current-state></current-state>
12</result>
        
Example response data when there is an input validation error
HTTP Status 400
 1{
 2    "status": "illegal-arguments",
 3    "message": "Illegal arguments.",
 4    "format": null,
 5    "program": "blastn",
 6    "datasets": "ddbjall",
 7    "database": "hum",
 8    "parameters": null,
 9    "querySequence": ">my query sequence 1\nCACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA\nGCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG\nGTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC\n",
10    "result": "",
11    "address": null,
12    "current-time": "2013-01-01 12:34:56",
13    "error-messages": [
14        "Required: (result)" 
15    ],
16    "error-message": "BAD_REQUEST (null)" 
17}

        

Usage Example

Example of the use of the REST client on Java Spring Framework:

import java.util.LinkedHashMap;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.client.HttpClientErrorException;
import net.arnx.jsonic.JSON;

/*
 * (Omitted)
 */

    MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
    parts.add("address", "");
    parts.add("database", "hum");
    parts.add("datasets", "ddbjall");
    parts.add("format", "json");
    parts.add("parameters", " -v 100 -b 100 -e 10 -F F -W 11");
    parts.add("program", "blastn");
    parts.add("querySequence", ">my query sequence 1\nCACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA\nGCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG\nGTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC\n");
    parts.add("result", "www");
    try {
        RestTemplate rest = new RestTemplate();
        String response = rest.postForObject("http://ddbj.nig.ac.jp/wabi/blast/", parts, String.class);
        /*
----  Example response (start)  --------------------------------
{
    "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
    "program": "blastn",
    "datasets": "ddbjall",
    "database": "hum",
    "parameters": " -v 100 -b 100 -e 10 -F F -W 11",
    "current-time": "2013-01-01 12:34:56",
    "start-time": "",
    "current-state": "" 
}
----  Example response (end)   --------------------------------
         */
        LinkedHashMap<String, String> result = JSON.decode(response, LinkedHashMap.class);
        String requestId = result.get("requestId");
        /*
         * Store the Request ID if the job was successfully added to the queue
         */
    }  catch (HttpClientErrorException e) {
        /*
         * Process input validation errors, other exceptions, etc. 
         */
    }

URI GET /blast/{Request-ID}?info=status (query the status of a search job)

Returns the status of the job specified by Request ID.

Item Description
HTTP Method GET
URI "/blast/" + Request ID + HTTP Parameter
(example: "/blast/wabi_blast_1111-1111-1111-11-111-111111?info=status")
HTTP Parameters info (default value = "status") Job information type (example: "status", "result")
format (default value = "text") Response data format (example: "text", "json")

Server-Side Processing Flow

  1. Input values are validated on the server side.
    If an input validation error is found, processing is interrupted, and the server returns HTTP status code 400 Bad Request.
  2. The server obtains job information corresponding to the specified Request ID and returns the current status.
    HTTP status code 404 is returned if the search retention period has expired or if the job information cannot be found.
  3. The server returns the obtained current job’s status using the specified format.
    However, the server returns HTTP status code 404 Not Found if the specified format is invalid.

Input value validation check performed

requestId
  1. Required value.
  2. Values containing any characters other than alphanumeric, "-", and "_" will cause an input validation error.
  3. Any Request ID that does not exist will cause an input validation error.
    Search results are discarded after a given period; it will be considered to be an input validation error in this case as well.
format
  1. Required value.
  2. Causes an input validation error if an undefined value is passed.
imageId
  1. Should not be specified.
info
  1. Must specify the value "status".

Response Data

In the case of successful completion:
Returns a "successful” HTTP status code such as 200.
The field status will contain information corresponding to “current status”.
Other values such as current-time and other request information may be included in the response data; however, formatting of these values may change in the future.
Please use the HTTP status code to determine the success or failure of the request.
In the case of failed completion:
Returns a “client error” HTTP status code such as 400.
The key called error-messages included in the returned data will contain an error message indicating such information as the name of the parameter that caused input validation error.
Other values including cause of the error and other request information may be included in the returned data; however, formatting of these values may change in the future.
Please use the HTTP status code to determine the success or failure of the request.

Example request and response

Example input values
HTTP Parameter nput value
format "json"
result "www"
info "status"
Example response for a successfully completed request
HTTP Status 200
1request-ID: wabi_blast_1111-1111-1111-11-111-111111
2status: finished
3current-time: 2013-01-01 12:34:56
4system-info:
5stdout
HTTP Status 200
1{
2        "request-ID": "wabi_blast_1111-1111-1111-11-111-111111",
3        "status": "finished",
4        "current-time": "2013-01-01 12:34:56",
5        "system-info": "\nstdout" 
6}
HTTP Status 200
1<?xml version="1.0" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<result>
4  <request-ID>wabi_blast_1111-1111-1111-11-111-111111</request-ID>
5  <status>finished</status>
6  <current-time>2013-01-01 12:34:56</current-time>
7  <system-info>stdout</system-info>
8</result>

Example response for a failed request
HTTP ステータス 400
 1{
 2        "status": "illegal-arguments",
 3        "message": "Illegal arguments.",
 4        "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
 5        "format": "json",
 6        "imageId": null,
 7        "info": "status",
 8        "current-time": "2013-01-01 12:34:56",
 9        "error-messages": [
10                "No such data: (requestId)" 
11        ],
12        "error-message": "BAD_REQUEST (null)" 
13}

        

Example Usage

Example using the REST client on Java Spring Framework:

import java.util.LinkedHashMap;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.client.HttpClientErrorException;
import net.arnx.jsonic.JSON;

/*
 * (Omitted)
 */

    /*
     * Submit GET request using a previously stored Request ID
     */
    String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
    MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
    parts.add("info", "status");
    parts.add("format", "json");
    try {
        RestTemplate rest = new RestTemplate();
        String response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/" + requestId, String.class, parts);
        /*
----  Example response (begin)  --------------------------------
{
    "request-ID": "wabi_blast_1111-1111-1111-11-111-111111",
    "status": "finished",
    "current-time": "2013-01-01 12:34:56",
    "system-info": "stdout" 
}
----  Example response (end)  --------------------------------
         */
        LinkedHashMap<String, String> result = JSON.decode(response, LinkedHashMap.class);
        String status = result.get("status");
        /*
         *  Job status given by the value of ‘status’ Example:  "waiting", "running", "finished" 
         */
    } catch (HttpClientErrorException e) {
        /*
         * Handle input validation errors, etc.
         */
    }

URI GET /blast/{Request-ID}?info=request (obtain and confirm search criteria)

This will return the search criteria of a specified Request ID.

Item Description
HTTP Method GET
URI "/blast/" + Request ID + "?info=request" + HTTP Parameters
(example: "/blast/wabi_blast_1111-1111-1111-11-111-111111?info=request")
HTTP Parameter format (default value = "text") Response data format (example: "text", "json")

Server-Side Processing Flow

  1. Input values are validated on the server side.
    If an input validation error is found, processing is interrupted, and the server returns HTTP status code 400 Bad Request .
  2. Information on the job specified by Request ID is retrieved, and the search criteria are returned.
    HTTP status code 404 is returned if the search retention period has expired or if the job information cannot be found.
  3. The server returns the current search criteria in the specified format.
    However, the server returns HTTP status code 404 Not Found if the specified format is invalid.

Input value validation check performed

requestId
  1. Required value.
  2. Values containing any characters other than alphanumeric, "-", and "_" will cause an input validation error.
  3. Specifying a Request ID that does not exist will cause an input validation error.
    Search results are discarded after a given period and requests for these results will also result in an input validation error.
format
  1. Required value.
  2. Causes an input validation error if an undefined value is specified.
imageId
  1. Should not be specified.
info
  1. Must specify the value "request"

Response Data

In the case of successful completion:
Returns a "successful” HTTP status code such as 200.
Response data contain each parameter included when the BLAST search job was initially submitted.
Please use the HTTP status code to determine the success or failure of the request.
In case of failed completion:
Returns a “client error” HTTP status code such as 400.
The key called error-messages included in the returned data will contain an error message with information such as the name of the parameter that caused the input validation error.
Please use the HTTP status code to determine the success or failure of the request.

Example request and response

Example input values:
HTTP Parameters Input values
format "requestfile"
info "request"
Example response for a successfully completed request:
HTTP Status 200
 1{
 2        "address": "",
 3        "database": "hum",
 4        "datasets": "ddbjall",
 5        "format": "text",
 6        "parameters": " -v 100 -b 100 -e 10 -F F -W 11 ",
 7        "program": "blastn",
 8        "querySequence": ">my query sequence 1\nCACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA\nGCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG\nGTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC\n",
 9        "result": "www" 
10}

        
Example response for a failed request:
HTTP Status 404
 1{
 2        "Message": "Unexpected error ( Results of your request id have been NOT FOUND.)",
 3        "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
 4        "format": "text",
 5        "imageId": null,
 6        "info": "result",
 7        "current-time": "2013-01-01 12:34:56",
 8        "error-messages": [
 9                "No such data: (requestId)" 
10        ],
11        "error-message": "NOT_FOUND (null)" 
12}

        

Example Usage

Example using the REST client on Java Spring Framework:

import java.util.LinkedHashMap;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.client.HttpClientErrorException;
import net.arnx.jsonic.JSON;

/*
 * (Omitted)
 */

    /*
     *  Submit GET request using a previously stored Request ID
     */
    String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
    MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
    parts.add("info", "request");
    parts.add("format", "json");
    try {
        RestTemplate rest = new RestTemplate();
        String response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/" + requestId, String.class, parts);
        /*
----  Example response (begin)  --------------------------------
{
    "address": "",
    "database": "hum",
    "datasets": "ddbjall",
    "format": "json",
    "parameters": " -v 100 -b 100 -e 10 -F F -W 11",
    "program": "blastn",
    "querySequence": ">my query sequence 1\nCACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA\nGCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG\nGTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC\n      ",
    "result": "www" 
}
----  Example response (end)   --------------------------------
         */
        LinkedHashMap<String, String> request = JSON.decode(response, LinkedHashMap.class);
        /*
         * ---- Example request (begin)  -------------------
         * request["address"] == "" 
         * request["database"] == "hum" 
         * request["datasets"] == "ddbjall" 
         * request["format"] == "json" 
         * request["parameters"] == " -v 100 -b 100 -e 10 -F F -W 11"
         * request["program"] == "blastn" 
         * request["querySequence"] == ">my query sequence 1\nCACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA\nGCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG\nGTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC\n"
         * request["result"] == "www" 
         * ---- Example request (end)  -------------------
         */
    } catch (HttpClientErrorException e) {
        /*
         * Handle input validation errors, etc.
         */
    }

URI GET /blast/{Request-ID}?info=result (retrieve search results)

Returns the search results for a specified Request ID.

Item Description
HTTP Method GET
URI "/blast/" + Request ID + "?info=result" + HTTP Parameters
(example: "/blast/wabi_blast_1111-1111-1111-11-111-111111?info=result")
HTTP Parameter format (default value = "text") Response data format (example: "text", "json")

Server-Side Processing Flow

  1. Input values are validated on the server side.
    If an input validation error is found, processing is interrupted, and the server returns HTTP status code 400 Bad Request.
  2. 2. Information on the job specified by Request ID is retrieved, and returns the search result.
    HTTP status code 400 or 404 is returned if the search retention period has expired or if the search processing has not yet completed.
  3. 3. The server returns the search result using the specified format.
    However, the server returns HTTP status code 404 Not Found if the specified format is invalid.

Input validation check performed

requestId
  1. Required value.
  2. Values containing any characters other than alphanumeric, "-", and "_" will cause an input validation error.
  3. Specifying a Request ID that does not exist will cause an input validation error.
    Search results are discarded after a given period and requests for these results will also result in an input validation error.
format
  1. Required value.
  2. Causes an input validation error if an undefined value is specified.
imageId
  1. Should not be specified.
info
  1. Must specify the value "result".

Response Data

In the case of successful completion:
Returns a "successful” HTTP status code such as 200.
Returns the content of the output file generated through the BLAST search.
Please use the HTTP status code to determine the success or failure of the request.
In the case of failed completion:
Returns a “client error” HTTP status code such as 400.
The key called error-messages included in the returned data will contain an error message with information such as the name of the parameter that caused the input validation error.
Please use the HTTP status code to determine the success or failures of the request.

Example request and response

Example of input data:
HTTP Parameters Input Value
format "bigfile"
info "result"
Example response for a successfully completed request
HTTP Status 200
 1BLASTN 2.2.25 [Feb-01-2011]
 2
 3Reference: Altschul, Stephen F., Thomas L. Madden, Alejandro A. Schaffer,
 4Jinghui Zhang, Zheng Zhang, Webb Miller, and David J. Lipman (1997),
 5"Gapped BLAST and PSI-BLAST: a new generation of protein database search
 6programs",  Nucleic Acids Res. 25:3389-3402.
 7
 8Query= AB000095|AB000095.1 Homo sapiens mRNA for hepatocyte growth
 9factor activator inhibitor, complete cds.
10         (1740 letters)
11
12Database: hum
13           572,091 sequences; 5,019,832,159 total letters
14
15Searching..................................................done
16
17                                                                 Score    E
18Sequences producing significant alignments:                      (bits) Value
19
20AB000095|AB000095.1 Homo sapiens mRNA for hepatocyte growth fact...  3449   0.0
21BC018702|BC018702.1 Homo sapiens serine peptidase inhibitor, Kun...  3435   0.0
22BC004140|BC004140.1 Homo sapiens serine peptidase inhibitor, Kun...  3190   0.0
23BT007425|BT007425.1 Homo sapiens serine protease inhibitor, Kuni...  3053   0.0
24AY358969|AY358969.1 Homo sapiens clone DNA35880 HAI-1 (UNQ223) m...  2145   0.0
25AY296715|AY296715.1 Homo sapiens hepatocyte growth factor activa...  1984   0.0

(Omitted)

        
Example response data when there is an input validation error
HTTP Status 400
 1{
 2        "Message": "Error ( Results of your request id have been NOT FOUND, or still running.)",
 3        "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
 4        "format": "text",
 5        "imageId": null,
 6        "info": "result",
 7        "current-time": "2013-01-01 12:34:56",
 8        "error-messages": [
 9                "No such data: (requestId)" 
10        ],
11        "error-message": "NOT_FOUND (null)" 
12}

        

Usage Example

Example of the use of the REST client on Java Spring Framework:

import java.util.LinkedHashMap;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.client.HttpClientErrorException;
import net.arnx.jsonic.JSON;

/*
 * (Omitted)
 */

    /*
     * Submit GET request using a previously stored Request ID
     */
    String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
    MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
    parts.add("info", "result");
    parts.add("format", "bigfile");
    try {
        RestTemplate rest = new RestTemplate();
        String response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/" + requestId, String.class, parts);
        /*
----  Example response (begin)   --------------------------------
BLASTN 2.2.25 [Feb-01-2011]

Reference: Altschul, Stephen F., Thomas L. Madden, Alejandro A. Schaffer,
Jinghui Zhang, Zheng Zhang, Webb Miller, and David J. Lipman (1997),
"Gapped BLAST and PSI-BLAST: a new generation of protein database search
programs",  Nucleic Acids Res. 25:3389-3402.

Query= AB000095|AB000095.1 Homo sapiens mRNA for hepatocyte growth
factor activator inhibitor, complete cds.
     (1740 letters)

Database: hum
       572,091 sequences; 5,019,832,159 total letters

Searching..................................................done

                                    Score    E
Sequences producing significant alignments:                      (bits) Value

AB000095|AB000095.1 Homo sapiens mRNA for hepatocyte growth fact...  3449   0.0
BC018702|BC018702.1 Homo sapiens serine peptidase inhibitor, Kun...  3435   0.0
BC004140|BC004140.1 Homo sapiens serine peptidase inhibitor, Kun...  3190   0.0
BT007425|BT007425.1 Homo sapiens serine protease inhibitor, Kuni...  3053   0.0
AY358969|AY358969.1 Homo sapiens clone DNA35880 HAI-1 (UNQ223) m...  2145   0.0
AY296715|AY296715.1 Homo sapiens hepatocyte growth factor activa...  1984   0.0
----  Example response (remainder omitted)   ------------------------------------
         */
    } catch (HttpClientErrorException e) {
        /*
         * Handle input validation errors, etc.
         */
    }

URI GET /blast/{Request-ID}?imageId={Image-ID} (retrieve image data generated from the search result)

This method returns the image data generated from the search result specified by RequestID.

Item Description
HTTP Method GET
URI "/blast/" + RequestID + "?imageId=" + Image ID + HTTP parameters
(example: "/blast/wabi_blast_1111-1111-1111-11-111-111111?imageId=1")
HTTP Parameters format (default value = "text") Response data format (example: "imagefile")

Server-side processing flow

  1. Input values are validated on the server side.
    If an invalid input value is found, then the processing is interrupted and HTTP status 400 Bad Request is returned.
  2. Information about the job corresponding to the specified RequestID is obtained, and the image generated from the BLAST search is returned.
    HTTP status code 400 or 404 is returned if the job information cannot be retrieved due to search retention period having expired or due to search job not having completed processing.
  3. The server returns the image generated from the BLAST search in the specified format.
    However, the server returns HTTP status code 404 Not Found if the specified formatis invalid.

Input validation check performed

requestId
  1. Required value.
  2. Values containing any characters other than alphanumeric, "-", and "_" will cause an input validation error.
  3. Specifying a requestId that does not exist will cause an input validation error.
    Search results are discarded after a given period and requests for these results will also result in an input validation error.
format
  1. Any value other than "imagefile" will result in an input error.
imageId

  1. Any value other than a numeric value will result in an input error.
info
  1. Returns an input error if an undefined value is specified.

Response Data

In the case of successful completion:
Returns a "successful” HTTP status code such as 200.
Returns the image data generated from the BLAST search.
Please use the HTTP status code to determine the success or failure of the request.
In the case of failed completion:
Returns a “client error” HTTP status code such as 400.
The key called error-messages included in the returned data will contain an error message with information such as the name of the parameter that caused the input validation error.
Please use the HTTP status code to determine the success or failure of the request.

Example request and response

Example input values
HTTP Parameter Input Value
imageId "1"
format "imagefile"
info ""
Example response for a successfully completed request
HTTP Status 200
(Image Data)
        
Example response for a failed request
HTTP Status 404
 1{
 2        "Message": "Error ( Blast image file of your request id have been NOT FOUND, or still running.)",
 3        "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
 4        "format": "text",
 5        "imageId": null,
 6        "info": "result",
 7        "current-time": "2013-01-01 12:34:56",
 8        "error-messages": [
 9                "No such data: (requestId)" 
10        ],
11        "error-message": "NOT_FOUND (null)" 
12}

        

Example Usage

Example using HttpURLConnection with Java:

import java.io.BufferedInputStream;
import java.io.File;
import java.io.FileOutputStream;
import java.net.URL;
import java.net.HttpURLConnection;

/*
 * (Ommitted)
 */

    /*
     *  In this example, retrieved file is saved.
     */
    File outputFile = ....;

    /*
     * Submit GET request using a previously stored Request ID.
     */
    String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
    URL url = new URL("http://ddbj.nig.ac.jp/wabi/blast/" + requestId + "?imageId=" + imageId);
    HttpURLConnection http = (HttpURLConnection)url.openConnection();
    http.setRequestMethod("GET");
    http.connect();
    int responseCode = http.getResponseCode();
    if (200<=responseCode && responseCode<=299) {
        BufferedInputStream inputStream = new BufferedInputStream(http.getInputStream());
        outputFile.createNewFile();
        FileOutputStream outputStream new FileOutputStream(outputFile);
        for (int data = inputStream.read(); -1!=(data = inputStream.read());) {
            outputStream.write(data);
        }
        inputStream.close();
        outputStream.close();
    } else if (400<=responseCode && responseCode<=499) {
        /*
         * Handle input validation errors, etc. 
         */
    } else {
        /*
         * Others
         */
    }

Example using the REST client on Java Spring Framework:
Note:Due to a known problem, image data conversion will fail when using the REST client.

import java.awt.image.BufferedImage;
import java.io.File;
import java.util.List;
import java.util.LinkedHashMap;
import javax.imageio.ImageIO;
import org.springframework.http.converter.BufferedImageHttpMessageConverter;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.client.HttpClientErrorException;

/*
 * (Omitted)
 */

    /*
     * In this example, save the retrieved image.
     */
    File outputFile = ....;

    /*
     * Submit GET request using a previously stored Request ID.
     */
    String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
    MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
    parts.add("imageId", "1");
    parts.add("format", "imagefile");
    try {
        RestTemplate rest = new RestTemplate();
        List converters = rest.getMessageConverters();
        converters.add(new BufferedImageHttpMessageConverter());
        rest.setMessageConverters(converters);
        BufferedImage response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/" + requestId, BufferedImage.class, parts);
        ImageIO.write(response, "PNG", outputFile);
    } catch (HttpClientErrorException e) {
        /*
         * Handle input validation errors, etc.
         */
    }

URI GET /blast/help/{Help-Command} (View help information)

Returns the help information of WABI BLAST.

Item Description
HTTP Method GET
URI "/blast/help/" + Help-Command + HTTP Parameter
(example: "/blast/help/list_program?format=json")
HTTP Parameters format (default value = "text") Response data format (example: "text", "json")
program BLAST program name (example: "blastn")

Help-Command

Help-Commands Other HTTP Parameters Help information that can be referenced
list_datasets List of defined values for the datasets parameter
list_database パラメーター データベース の定義値の一覧
list_program List of defined parameters for the BLAST program parameter
list_parameters program = BLAST program List of defined optional parameters for the specified BLAST program
list_format List of defined values for the response data parameter
list_result List of defined values for the result parameter
list_info List of defined parameters for job information to be retrieved

Response data

In the case of successful completion:
Returns the requested help information
In case of failed completion:
Returns the list of valid Help-Commands and other information.

Example request and response

Example input values:
Help-Command and other parameters nput Values
Help-Command "list_result"
format "json"
Example response for a successfully completed request:
1{
2    "result": [
3        "www",
4        "mail" 
5    ]
6}

        
Example response for a failed request:
 1{
 2    "help_commands": [
 3        "list_datasets",
 4        "list_database",
 5        "list_program",
 6        "list_parameters",
 7        "list_format",
 8        "list_result",
 9        "list_info" 
10    ],
11    "format": [
12        "text",
13        "json",
14        "xml" 
15    ]
16}

        

Example Usage

Example of the use of the REST client on Java Spring Framework:

import java.util.LinkedHashMap;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.client.HttpClientErrorException;
import net.arnx.jsonic.JSON;

/*
 * (Omitted)
 */

        MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
        parts.add("format", "json");
        RestTemplate rest = new RestTemplate();
        String response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/help/list_result", String.class, parts);
        /*
----  Example response (begin)  --------------------------------
{
    "result": [
        "www",
        "mail" 
    ]
}
----  Example response (end)   --------------------------------
         */
        LinkedHashMap<String, Object> result = JSON.decode(response, LinkedHashMap.class);
        String result0 = (List<String>)result.get(0);
        /*
         * 例:
         * result.size() == 2
         * result0 == "www" 
         */
ページの先頭へ戻る