[2021-06-11] Important update:
The public repository "Demo B2B Server" has been launched containing the code to illustrate the API functionalities of Bio2Byte Tools (Jupyter Notebook is available). More details on Readme file.
API METHODS
Send request
Use below request to send your data to the API.
-
URL:
https://bio2byte.be/msatools/api/
-
METHOD: POST
-
DATA FORMAT: JSON
{ "tool_list": ["efoldmine"], "token": "YOURTOKEN", "MyProteinIdentifier1": "SEQINAALETTERS", "MyProteinIdentifier2": "DIFFERENTSEQINAALETTERS", "MyProteinIdentifierN": "SEQUENCENTH" }
The token value (YOURTOKEN) can be set to your own private key, so that only you can retrieve the results on the website later (using this exact token). It must have a length of 10 characters.
-
SUCCESS RESPONSE:
Code = 202 Accepted
{ "Location": "/api/queue/hash_ID/", "hash_id": hash_ID, "message": "We are processing your request, check queue to be updated about the processing status" }
You have to track and use the hash_ID generated by the API to access your results; this is in effect the queue identifier that enables only you to check the processing status and get the results.
-
ERROR RESPONSE:
Code = 400 Bad Request, Content = {}
cURL command
cURL is a tool to transfer data from or to a server, using one of the supported protocols (HTTP, HTTPS, etc.). The command is designed to work without user interaction.
$ curl --location --request POST 'https://bio2byte.be/msatools/api/' \
--header 'Content-Type: application/json' \
--data-raw '{
"tool_list": ["efoldmine"],
"token": "YOURTOKEN",
"MyProteinIdentifier1": "SEQINAALETTERS",
"MyProteinIdentifier2": "DIFFERENTSEQINAALETTERS",
"MyProteinIdentifierN": "SEQUENCENTH"
}'
Get queue status
Use below request to get information about the status of your API request.
-
URL:
https://bio2byte.be/msatools/api/queue/hash_ID
-
METHOD: GET
-
SUCCESS RESPONSE:
-
Code = 202 Accepted
{ "hash_id": hash_ID, "id": ID, "location": "not_available", "request_text": "We are processing your request, there are still N processes", "status": 202 }
-
Code = 303 See other
{"Location": "/api/hash_ID"}
-
-
ERROR RESPONSE:
Code = 404 Not found, Content = {}
cURL command
cURL is a tool to transfer data from or to a server, using one of the supported protocols (HTTP, HTTPS, etc.). The command is designed to work without user interaction.
$ curl --location --request GET 'https://bio2byte.be/msatools/api/queue/hash_ID'
Get results
Use below request to get your prediction results in JSON format, once they are calculated. Note that all predictions that were required to get the result you requested are included.
-
URL:
https://bio2byte.be/msatools/api/hash_ID
-
METHOD: GET
-
SUCCESS RESPONSE:
Code = 200 Ok
{ "creation_date": "yyyy-mm-ddTHH::MM.millisecZ", "id": ID, "hash_id": hash_ID, "results": [ { "efoldmine": [val1, val2, val3, ..., valn], "proteinID": "proteinid1", "sequence": "sequence1" } ], "token": "YOURTOKEN", "tool": "efoldmine" }
-
ERROR RESPONSE:
Code = Not found, Content = {}
cURL command
cURL is a tool to transfer data from or to a server, using one of the supported protocols (HTTP, HTTPS, etc.). The command is designed to work without user interaction.
$ curl --location --request GET 'https://bio2byte.be/msatools/api/hash_ID'
API CALL EXAMPLE
Below describes an example to get data from the API via the command line using httpie ($ apt install httpie
). The format of the input_file.json
is described at the top of this document.
For instance, the content of the example path/input_file.json is:
{
"tool_list": ["efoldmine"],
"token": "YOURTOKEN",
"Q647G9": "MAKSTILALLALVLVAHASAMRRERGRQGDSSSCERQVDRVNLKPCEQHIMQRIMGEQEQYDSYDIRSTRSSDQQQRCCDELNEMENTQRCMCEALQQIMENQCDRLQDRQMVQQFKRELMNLPQQCNFRAPQRCDLDVSGGRC",
"P67966": "MPNWGGGKKCGVCQKAVYFAEEVQCEGSSFHKSCFLCMVCKKNLDSTTVAVHGDEIYCKSCYGKKYGPKGYGYGMGAGTLSTDKGESLGIKYEEGQSHRPTNPNASRMAQKVGGSDGCPRCGQAVYAAEKVIGAGKSWHKSCFRCAKCGKSLESTTLADKDGEIYCKGCYAKNFGPKGFGFGQGAGALIHSQ",
"O04311": "MAQKVEAGGGAGGASWDDGVHDGVRKVHVGQGQDGVSSINVVYAKDSQDVEGGEHGKKTLLGFETFEVDADDYIVAVQVTYDNVFGQDSDIITSITFNTFKGKTSPPYGLETQKKFVLKDKNGGKLVGFHGRAGEALYALGAYFATTTTPVTPAKKLSAIGGDEGTAWDDGAYDGVKKVYVGQGQDGISAVKFEYNKGAENIVGGEHGKPTLLGFEEFEIDYPSEYITAVEGTYDKIFGSDGLIITMLRFKTNKQTSAPFGLEAGTAFELKEEGHKIVGFHGKASELLHQFGVHVMPLTN",
"P24937": "MEDINFASLAPRHGSRPFMGNWQDIGTSNMSGGAFSWGSLWSGIKNFGSTVKNYGSKAWNSSTGQMLRDKLKEQNFQQKVVDGLASGISGVVDLANQAVQNKINSKLDPRPPVEEPPPAVETVSPEGRGEKRPRPDREETLVTQIDEPPSYEEALKQGLPTTRPIAPMATGVLGQHTPVTLDLPPPADTQQKPVLPGPTAVVVTRPSRASLRRAASGPRSLRPVASGNWQSTLNSIVGLGVQSLKRRRCF"
}
-
Send request to webserver
$ http POST https://bio2byte.be/msatools/api/ < path/input_file.json
-
Response example
{ "Location": "/api/queue/ZQcAD8DZOWsQwqOX82yP/", "hash_id": "ZQcAD8DZOWsQwqOX82yP", "message": "We are processing your request, check queue to be updated about the processing status" }
-
Check queue request status
$ http --follow GET https://bio2byte.be/msatools/api/queue/ZQcAD8DZOWsQwqOX82yP/
-
Responses example
-
Case 1: Results still not available (You have to call the server again to check if your results are available)
{ "hash_id": "ZQcAD8DZOWsQwqOX82yP", "id": 5, "location": "not_available", "request_text": "We are processing your request, there are still 2 processes", "status": 202 }
-
Case 2: Results available (If you use
--follow
option inhttpie
you will be automatically redirected to results.){ "hash_id": "ZQcAD8DZOWsQwqOX82yP", "id": 5, "location": "/api/ZQcAD8DZOWsQwqOX82yP/", "request_text": "Results available at /api/ZQcAD8DZOWsQwqOX82yP/", "result_id": ZQcAD8DZOWsQwqOX82yP }
-
-
Get your results
$ http --follow GET https://bio2byte.be/msatools/api/ZQcAD8DZOWsQwqOX82yP/
-
Result response example
{ "creation_date": "2021-01-10T21:51:25.686172Z", "hash_id": "ZQcAD8DZOWsQwqOX82yP", "id": 52, "results": [ { "proteinID": "P67966", "sequence": "MPNWGGGKKCGVCQKAV...", "efoldmine": [ 0.4611470401287079, 0.4550575315952301, ... ], }, { "proteinID": "P01139", "sequence": "MSMLFYTLITAFLIGVQ....", "efoldmine": [ 0.43476158380508423, 0.4361424148082733, .... ], }, ], "token": "YOURTOKEN", "tool": "efoldmine" }
The user can access the APIs that require an input file using a Python script as described in the example below.
-
Send request
#!/usr/bin/env python import requests, json ## input parameters ## url = 'https://bio2byte.be/msatools/api/' tool_list = ['efoldmine'] # The selected tool token = 'YOURTOKEN' # Your personal token ID1 = 'my_seq' # First sequence identifier SEQ1 = 'MESNQSNNGGSGNAALNRGGRYVPPHLRGGDGGAAAAASAGGDDRRGGAGGGGYRRG' # First sequence ID2 = 'my_dif_seq' # Second sequence identifier SEQ2 = 'MASTDYSTYSQAAAQQGYSAYTAQPTQGYAQTTQAYGQQSYGTYGQPTDVSYTQAQTTAT' # Second sequence values = {'tool': tool, 'token': token, ID1: SEQ1, ID2: SEQ2} r = requests.post(url, data=values) queue_url = json.loads(r.content.decode("utf-8"))["Location"] queue_status_url = 'https://bio2byte.be/msatools' + queue_url print('Success: go to: ' + queue_status_url)
-
Get request
#!/usr/bin/env python import requests # Use the hash_id from the previous step's response hash_id = 'O4X8cOs6KexeeW22QD2W' url = 'https://bio2byte.be/msatools/api/queue/' + hash_id response = requests.get(url) print(response.content)