Annotation server API

PubAnnotation defines REST API for interoperability.

A PubAnnotation-interoperable annotations server is defined as a RESTful web service which conforms the following input and output API.

Input

A PubAnnotation-interoperable annotation server takes either

  • a piece of text through the parameter, text, or
  • a pair of source DB and source ID specification through the parameter, sourcedb and sourceid.

When a request is made with text, the server is expected to produce annotations to the text, and to respond with the annotations.

When a request is made with sourcedb & sourceid, the server is expected to fetch the corresponding piece of text from the source DB, to produce annotations to the text, and to respond with the annotations.

Making a request with both text and sourcedb/sourceid may cause a redundant specification. In the case, it is expected that the text parameter takes higher priority with the sourcedb/sourceid specification ignored.

Output

PubAnnotation expects an annotation server to respond with annotations represented in PubAnnotation JSON format.

In case an annotation server supports multiple options of annotation formats, the format of response body the client will expect may be speficied in the URL or in the Accept header.

While different people advocate different approach, there may be pros and cons in both: see this dicussion.

However, either should be fine with PubAnnotation.

For the case where a server replies on Accept header to determine the output format of annotations, PubAnnotation will add the Accept header to every requests it will make.

In case a server see the URL, e.g. type extention, to determine the format of output, which is the case of PubAnnotation, the server can simply ignore the Accept header.

Asynchronous output

[changes made at 21st Feb, 2017] The Retry-After header can be sent with the response of the initial request (not the second).

[changes made at 21st Feb, 2017] For the second request, the response code for the case the result of annotation is not (yet) available is changed to 404 from 503.

[changes made at 21st Feb, 2017] For the second request, the response code for the case the result of annotation is permanently removed is changed to 410 from 404.

In case an annotation server requires a separate request for retrieval of annotations, the server has to response to the initial request with the status code 303 (See Other) and the Location header has to indicate the URL for the client to access to retrieve the annotations. Optionally, the Retry-After header can be used to indicate how long the clinet is advised to wait before accessing the location of annotation result. If the server cannot fulfil the request for some reason, e.g., server overload, it has to respond with the status code 503 (Service Unavailable). It will inform the client that the request is fine, and that a later attempt with the same request may be successful.

When the request to retrieve the result of annotation is made, if ready, the server has to respond with the status code 200 (OK) and the body has to deliver the result of annotation.

If the server is not ready with annotations, it has to respond with the status code 404 (Not Found).

After annotations are delivered to the client, if the server removes the annotations, the annotations will not be available any more from the server. In the case, the server can respond with the status code 410 (Gone).

As a model implementation, the API for asynchronous annotation request and retrieval is implemented in PubDictionaries. Please take a look at the corresponding API documentation: PubDictionaries Annotation API

Example

For an annotation server to be interoperable with PubAnnotation, it has to respond at least one of the example calls shown below.

Note that all the examples below are shown as cURL commands, so that annotation servers can be easily tested.

Note also that PubAnnotation will add “Accept:application/json” header to every request it will made, so that annotation servers which implement content negotiation can respond with annotation in JSON format. The servers which do not implement content negotiation can simply ignore the header.

a POST request with a piece of text

Note that when the -d option is used to specify parameters, cURL will make it into a POST request.

a GET request with a piece of text

Note that the -G option will force it to be a GET request: the parameter specification will be appended to the URL.

a POST request with a piece of text (in JSON body)

Note that the header “Content-Type:application/json” is added to inform the annotation server that the body of the request is a JSON object.

Note that the three examples above essentially represent the same request in different ways.

a POST request with sourcedb/sourceid specification

a GET request with sourcedb/sourceid specification

a POST request with sourcedb/sourceid specification in JSON.