Last modified April 10, 2017

BeCalm REST API

This document describes how make available your entity recognition tool using a REST API and be able to participate TIPS (Technical interoperability and performance of annotation servers) task. This task will focus on the technical aspects of the evaluation of continuous text Annotation Servers for named entity recognition. This is an open task, in the sense that it is not restricted to a particular named entity recognition task. Moreover, the annotation servers may be fully developed in-house or integrate third party recognition software as building block components (see list of initial existing candidate bio-NER tools). You can find more about TIPS challenge here .

The authentication is used to recognise both BeCalm metaserver and annotation server in a communication. Two types of authentication are possible in BeCalm:

HTTP Basic Auth

HTTP Basic Auth (or Basic access authentication) is a widely used protocol for simple user email/server key authentication.

As ApiKey in URL

Add the server ApiKey in the URL for all operations. For example: http://www.becalm.eu/api/annotations?apikey=2ds1f23sad1f132as

The authentication keys are provided after finishing the creation of the annotation server.

In order to connect the BeCalm REST API, it is mandatory to use the Annotation server REST API key.

In order to authenticate the BeCalm requests, there is a key that it will be included in all requests BeCalm request secret key.

Every server has its own pair authentication passwords.

Locate server passwords
API methods
saveAnnotations
Type:  POST
It allows saving the annotations in different formats. Example of URL: http://www.becalm.eu/api/saveAnnotations/[JSON|TSV|BIOC]?apikey={VALUE}&communicationId={VALUE} .

Note that apikey is located in the server view and the communicationId will be provided in the annotation request.

JSON This is the default format to save annotations in REST API. The JSON schema can be downloaded here . Next, an example of a annotation request is shown:
                                                                
                                                                [
                                                                    {
                                                                      "document_id": "CA2073855C", // Mandatory
                                                                      "section": "T", // title or abstract Mandatory
                                                                      "init": 0, // Mandatory
                                                                      "end": 14, // Mandatory
                                                                      "score": 0.856016, // Recommended
                                                                      "annotated_text": "Glycoalkaloids", // Mandatory
                                                                      "type": "unknown", // Unknown by default
                                                                      "database_id": "ED5266,ED5268" // Database IDs is recommended
                                                                    },                                                                  
                                                                ]
                                                                
                                                                
TSV The TSV file format is inspired in the traditional BioCreative TSV format. Below is an example of a TSV annotation request:
                                                                
                                                                DOCUMENT_ID SECTION INIT END SCORE ANNOTATED_TEXT TYPE DATABASE_ID
                                                                CA2095708C A 204 210 0.961811 carbon unknown 11
                                                                CA2095708C A 224 232 0.961811 hydrogen unknown 12
                                                                CA2095708C A 407 415 0.961811 hydrogen unknown 13
                                                                CA2095708C A 236 243 0.933887 hydroxy unknown 14
                                                                CA2095708C A 423 428 0.923149 alkyl unknown 15
                                                                CA2095708C A 342 349 0.901816 carboxy unknown 16
                                                                CA2095708C A 0 10 0.558573 N-aralkyl- unknown 17
                                                                CA2095708C A 15 58 0.528508 N-heteroaralkyl-aminoalkanephosphinic acids unknown 18
                                                                CA2095708C T 6 16 0.507779 n-aralkyl- unknown 19
                                                                CA2095708C A 158 177 0.480037 heteroarylaliphatic unknown 20
                                                                CA2095708C A 90 99 0.423316 aliphatic unknown 21
                                                                CA2095708C A 269 288 0.383323 heteroarylaliphatic unknown 22
                                                                
                                                                
BIOC The BioC.dtd can be downloaded from here.
You can see more about the BioC project here

This is one example of a BioC annotation request:

                                                                
                                                                
                                                                    <!DOCTYPE collection SYSTEM 'BioC.dtd'>
                                                                    <collection>
                                                                        <source>PUBMED</source>
                                                                        <date>2016-07-29 13:44:23</date>
                                                                        <key>BeCalm_579b4197423f0</key>
                                                                        <document>
                                                                            <id>CA2077637C</id>
                                                                            <passage>
                                                                                <infon key="type">title</infon>
                                                                                <offset>0</offset>
                                                                                <text>
                                                                                    Compositions comprising a tramadol material and any of 
                                                                                    codeine, oxycodone or hydrocodone and their use
                                                                                </text>
                                                                            </passage>
                                                                            <passage>
                                                                                <infon key="type">abstract</infon>
                                                                                <offset>103</offset>
                                                                                <text>
                                                                                This invention relates to compositions comprising a tramadol material
                                                                                and any of codeine, oxycodone or hydrocodone, and their use.
                                                                                The compositions are pharmacologically useful in treating pain,
                                                                                diarrhea and tussive conditions. The compositions are also subject to
                                                                                less side-effects as compared to pure opiate based compositions,
                                                                                such as abuse liability, tolerance, constipation and respiratory depression.
                                                                                Furthermore, where the components, i.e., a tramadol material and any of codeine,
                                                                                oxycodone or hydrocodone, of the compositions are within certain ratios
                                                                                the pharmacological effects of the compositions are superadditive (synergistic).
                                                                                </text>
                                                                                <prediction id="204">
                                                                                    <infon key="type">TRIVIAL</infon>
                                                                                    <location offset="103" length="11" />
                                                                                    <text>hydrocodone</text>
                                                                                </prediction>
                                                                            </passage>
                                                                        </document>
                                                                    </collection>
                                                                
                                                                
                                                                
updateServerState
Type:  POST
To publish the state of the server, including the server version and the maximum number of documents that is able to evaluate per day.

These are the possible options for the state parameter:

State Description
Running The server is working properly. This is the normal state
Suspended The server has been disabled by the administrator (e.g. server down for maintenance).
Shutdown The server is shutdown or not responding.
Overloaded The server is busy or at its full capacity and is not able to handle more requests for the time being.
Unknown The state of the server is unknown.
Working The server is already working in one project and can not be used at the moment.
Pending There is no response from the server yet.

Next, an example of a state request is shown:

                                                    
                                                
                                                {
                                                    "status": 200, // Mandatory (see the examples of status codes for more detail)
                                                    "success": true, // Mandatory 
                                                    "key":"616c202a947a0b9fed34" // Mandatory. Unique REST API server key to identify the annotation server
                                                    "data": 
                                                    {
                                                        "state":"Overloaded", // Mandatory. State of the server
                                                        "version":"4.4.3", // Mandatory. Current version of the server
                                                        "version_changes":"Description of changes", // Mandatory. Version description
                                                        "max_analyzable_documents":"515" // Mandatory. Maximum number of accepted documents per day
                                                                                         //Not used in the phase 1º-3º of the TIPS task
                                                    }
                                                }
                                            
                                            

The following section explains the various methods (and parameters) that must be implemented by the annotation server.

Request
Default parameters in all requests
The following JSON has the default parameters that are sent in all requests:
                                                     
                                                      {                                                        
                                                        "name":"BeCalm", // metaserver name
                                                        "method":"getAnnotations", // Method name (see next table)
                                                        "becalm_key":"616c202a947a0b9fed34", // Unique server key to identify BeCalm. This key is in order to 
                                                                                             //identify the BeCalm" metaserver 
                                                        "custom_parameters" :{"example":true}, // Custom parameters that could be set by the 
                                                                                               //user for de own server configuration 
                                                        "parameters" : {} // Method's dependencies (see next table)
                                                      }
                                                     
                                                
Request Methods
Method Responds with Example of request body
getAnnotations saveAnnotations
                                                                                                                                                                                                                                                                            
                                                                 {
                                                                    "name":"BeCalm", 
                                                                    "method":"getAnnotations", 
                                                                    "becalm_key":"616c202a947a0b9fed34", 
                                                                    "custom_parameters" :{"example":true}, 
                                                                    "parameters" : {
                                                                        "documents":[ // Documents to be parsed in order to obtain annotations. 
                                                                            // Detection of source name should be case insenstive
                                                                            {"document_id":"CA2073855C","source":"PATENT SERVER"},
                                                                            {"document_id":"1234567","source":"ABSTRACT SERVER"},
                                                                            {"document_id":"1234567","source":"PUBMED"},
                                                                            {"document_id":"PMC1234567","source":"PMC"}
                                                                        ],
                                                                        "types" : ["Identifier","Family"], // E.g. annotation types
                                                                        "expired": "2017-10-06T19:57:34+02:00",  // Maximum date to return a response (ISO-8601)
                                                                        "communication_id":1581 // Request identifier 
                                                                                                (used in the saveAnnotations response)
                                                                    }
                                                                 }
                                                                
                                                            
Documents will not be provided by BeCalm. Documents should be retrieve from the specified source. Sources can be: BeCalm patent server, BeCalm abstract server, PubMed, or PMC.
The BeCalm patent server and the BeCalm abstract server are available at:

Patents or abstracts can be retrieved in two formats:

getState
                                                                
                                                                 {
                                                                    "name":"BeCalm", 
                                                                    "method":"getState", 
                                                                    "becalm_key":"616c202a947a0b9fed34", 
                                                                    "custom_parameters" :{"example":true}, 
                                                                    "parameters" : {}
                                                                 }
                                                                
                                                            

In order to be able to handle BeCalm requests, the annotation server must accomplish the following requirements.

The BeCalm metaserver must contact with the developed annotation server in order to get the estate, send annotation requests, etc. In order to verify and confirm the correct reception of this requests its needed responds with the next JSON.

Responses
Get state response
The BeCalm metaserver must be able to connect with the annotation server to obtain different annotation server parameters via GET or POST requests (e.g. obtaining the server status). The response syntax is as follows:
                                                     
                                                      {
                                                        "status": 200, // Mandatory (see examples of status codes for more detail)
                                                        "success": true, // Mandatory
                                                        "key":"616c202a947a0b9fed34", // Mandatory. Unique key to identify BeCalm in your annotation server.
                                                                                     // It is used in all requests and responses
                                                        "data":
                                                            {
                                                                "state":"Overloaded", // Mandatory. State of the server
                                                                "version":"4.4.3", // Mandatory. Current version of the server
                                                                "version_changes":"Description of changes", // Mandatory. Version description
                                                                "max_analyzable_documents":"515" // Mandatory. Maximum number of accepted documents per day
                                                            }
                                                      }
                                                      
                                                      
                                                      
                                                      
                                                     
                                                
Annotation request response

The getAnnotations BeCalm method requires an acknowledgement response.

The BeCalm metaserver contacts the annotation server sending a JSON annotation request (see BeCalm metaserver request section). BeCalm metaserver waits for an acknowledgement response indicating that the request has been accepted by the annotation server (see next JSON) and then, closes the connection. Later, when the annotation server finishes the annotation job, it opens a new connection to the BeCalm metaserver and sends a saveAnnotations.
                                                     
                                                      //Annotation server acknowledgement response
                                                      {
                                                        "status": 200, // Mandatory (see examples of status codes for more detail)
                                                        "success": true, // Mandatory
                                                        "key":"616c202a947a0b9fed34" // Mandatory. Unique key to identify BeCalm in your annotation server. 
                                                                                    // It is used in all requests and responses
                                                      }
                                                     
                                                

Below are explained the BeCalm responses:

Responses
Success response
This is the general syntax of a BeCalm response when the operation is successful:
                                                     
                                                      {
                                                        "status": 200, 
                                                        "success": true,
                                                        "becalm_key":"616c202a947a0b9fed34", // Unique server key to identify BeCalm in your annotation server. 
                                                                                           // This key is used in all requests and responses
                                                        "data": {} // Returned data (if needed)
                                                      }
                                                     
                                                
Error response

The general syntax of an error message is as follows:

                                                     
                                                       {
                                                        "status": 400,
                                                        "success": false,
                                                        "message": "Almost one of your annotations has not a validated type. Please, review the validated types",
                                                        "errorCode": "6",
                                                        "becalm_key":"616c202a947a0b9fed34" // Unique server key to identify BeCalm. This key is used in all requests and responses.
                                                      }
                                                     
                                                

Below are explained the different status that BeCalm can send in the JSON error response:

Code Description
200 (OK) The data in the request is OK.
400 (BAD REQUEST) Invalid data in the request. Some examples are: missing data, incorrect fields, etc.
401 (UNAUTHORIZED) Missing or invalid authentication token.
403 (FORBIDDEN) The user is not authorized to perform the operation, i.e. does not have permissions to access the resource or the resource is unavailable for some reason (e.g. time constraints).
404 (NOT FOUND) The requested resource is not found, either it does not exist or there is a 401 or 403 code.
500 (INTERNAL SERVER ERROR) General catch-all error when the server-side throws an exception.

Below are explained the different possibilities of the "errorCode" parameter in the JSON error response

Code Name Description
1 FORMAT_ERROR The introduced format is not correct. Please, revise it and send your petition again.
2 INCORRECT_TRANSFER_REQUEST_METHOD The request method is invalid. Please, use POST in order to send your data.
3 VALIDATIONS_ON_SAVE The data could not be saved due to an unexpected error. Please, try again later.
4 EMPTY_DATA There is no data in the response. Please, add some data in the POST message.
5 PREDICTION_WITHOUT_TYPE At least one of the types are not recognized in our servers. Please, contact us to find a solution.
6 UNKNOWN_TYPE At least one of the types are not recognized in our servers. Please, contact us to find a solution.
7 DOCUMENT_NOT_FOUND Incorrect document id. At least one of the documents are not present in the BeCalm request
8 NOT_VALID_BY_SCHEMA The structure of the output annotation file is incorrect. Please, revise them and try again.
9 REQUEST_EXPIRED The time for responding to the request has expired. Please, try again.
10 UNKNOWN_COMMUNICATION_ID This communication id does not correspond to your annotation server. Please, contact us to find a solution.
11 SERVER_VERSION_CHANGED The version of the requested server has changed. Please, send the annotation request again.
12 NEED_PARAMETERS Some mandatory parameters are missing for the current operation. Please, check the API REST documentation and try again.
13 REQUEST_CLOSED The request has been executed properly.
14 FIELD_NEEDED There are some fields missing in the annotation response. Please, revise them and try again.
15 INCORRECT_FIELD There are some incorrect fields in the annotation response. Please, revise them and try again.
16 REPEATED_PREDICTION There are some annotations overlaped in the annotation response. Please, revise them and try again.
17 JSON_ERROR The JSON response is invalid and some fields has some errors. Please, revise them and try again.
18 INCORRECT_STATE The annotation server state is incorrect. Please, revise them or contact us to find a solution.
19 DISALLOWED_ENCODING Your annotations do not have a valid UTF-8 encoding.Please check your encoding and try again

Here are some examples for start developing the annotation server (click to download):