Last modified March 10, 2017
BeCalm REST API
How can I make available my Annotation Server via the BeCalm platform?
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.
BeCalm API REQUEST STEPS
Step 1 - Annotation server registration
A participant team want to register its annotation server in BeCalm. To do this, they have to login in the BeCalm web site and register the annotation server using the corresponding formulary (see BeCalm TIPS tutorial for more information).
It is important to remember that when the server is registered, BeCalm generates a pair of keys that will be used to identify both Annotation server and BeCalm in all REST API operations.
Step 2 - BeCalm getAnnotations() request
BeCalm sends a getAnnotations() request to the annotation server in order to obtain annotations for a set of documents. This request is a message that goes through Internet until reach the annotation server. Note that, it is imperative that the annotation server must be continously listening to BeCalm petitions to maintain a communication.
The getAnnotations() message is in JSON format and the BeCalm request secret key, obtained at the end of annotation server registration, is included in order to identify BeCalm server in your annotation server.
Step 3 - Annotation server getAnnotations() acknowledgement
Once the Annotation server receives the getAnnotations() request, it must respond to BeCalm with an acknowledge message. BeCalm metaserver will be waiting this confirmation.
The getAnnotations() acknowledgement is in JSON format and the Annotation server Rest API key, obtained at the end of annotation server registration, is needed in order to identify the Annotation server in the communication.
Step 4 - Annotation process
After received the acknowledgement, the Annotation server must execute its internal workflow to annotate the received documents from the BeCalm request. There are two mandatory conditions that every Annotation server must obey:
- The retrieved documents must be downloaded from their specific sources (see the 'source' parameter in the JSON request). This means, it is forbidden to cache any document.
- The Annotation server must output the annotations in one of the formats accepted by BeCalm (see saveAnnotations method for more information).
Step 5 - Annotation server saveAnnotations() request
After the annotation process end, the Annotation server must send annotations to BeCalm.
The request must be done to
The annotation server must specify the output format,
their Annotation server Rest API key and the communication id (see saveAnnotations method for more information).
The request body of the saveAnnotations() message depends on the specified format in the request. The figure shown an example of JSON format.
Step 6 - Becalm saveAnnotations() acknowledgement
Once BeCalm receives the saveAnnotations() request it validate and save all annotations. When the process ends it respond to Annotations server with an acknowledge message. Annotation server must wait this confirmation to check if the operation finish without errors.
The saveAnnotations() acknowledgement is in JSON format and the BeCalm request secret key, obtained at the end of annotation server registration, is included in order to identify BeCalm server in your annotation server.
It allows saving the annotations in different formats. Example of URL:
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:
Next, an example of a state request is shown:
BeCalm requests to annotation server
The following section explains the various methods (and parameters) that must be implemented by the annotation server.
|Default parameters in all requests||
The following JSON has the default parameters that are sent in all requests:
Mandatory annotation server responses
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.
|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:
|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.
BeCalm response examples and error codes
Below are explained the BeCalm responses:
This is the general syntax of a BeCalm response when the operation is successful:
The general syntax of an error message is as follows:
Below are explained the different status that BeCalm can send in the JSON error response:
Below are explained the different possibilities of the "errorCode" parameter in the JSON error response