… _common_rest_interface:

Service Gateway interface documentation

Purpose

The Service Gateway is essentially a Gateway from an HTTP REST interface to Celery/AMQP interface.

This document describes the WEB service interfaces that are common for each service which can be exposed by the current Service Gateway.

It shows how a service can be used, the standard response types and how to handle exceptions.

Methods

Most methods are supplied my an underlying package which offers base methods to control Service workers, including the basic routes required by the CANARIE Service API.

The Service Gateway builds on top of these methods and offers more specific functionalities.

See Rest interface overview for general information on the REST interface. All of the functions provided by the common REST interface are also available in this element.

The Service Gateway REST interface is used to launch and monitor an annotation processing request for a given document using any of the supported annotator services.

It covers:

• <Base URI>/annotate
• <Base URI>/status
• <Base URI>/cancel

Where <Base URI> will look like <Server>/<annotator_name>. e.g.:

http://vesta.crim.ca/diarisation

The specific service documentation should be checked to have an overview of supported services.

annotate

Launch the processing for a given document. Optionally store resulting annotations on a remote Annotations Storage Service when supplying annotation document UUID.

This method uses HTTP POST.

Parameters:

storage_doc_id:Storage document id given by the Multimedia Storage Service. doc_url:[Optional] URL of document to be processed (Can be used in replacement of the storage_doc_id). ann_doc_id:[Optional] argument giving Annotations Storage Service document ID to which the annotations will be appended. If the user omits this variable the annotator will not call any Annotations Storage Service but will log a Warning message with information regarding this fact.

Any additional parameters which are passed at request time that do not correspond to the parameter names above are forwarded to the annotation worker through a data structure with the “misc” key. The key value pair names are kept. This enables a developer to use arbitrary argument names in the HTTP request that will be forwarded to a given service through the JSON data structure communicated across AMQP/Celery.

Return value:

The service returns a JSON structure containing an «uuid» identifying the processing request:

{
    "uuid": "6547137e-cc2f-4008-b1eb-4ae8e898ce83"
}

The resulting «uuid» can then be used to perform further status queries to the service.

Note

If there is a need to use an Annotations Storage Service as a back-end the configuration of the LoadBalancer must specify the Annotations Storage Service storage URL to which the annotations will be appended via a HTTP POST call. See Configuration section.

Examples:

URL form:

<Base URI>/annotate/5hEK1ToPWHVhE3Irje5KRq.mp4?ann_doc_id=541a0ebb1747d5305901b48a

Alternatively:

<Base URI>/annotate?doc_url=http://localhost:8000/short_en.wav

With the curl utility:

curl -X POST --data-urlencode ann_doc_id=541a0ebb1747d5305901b48a\
    <Base URI>/annotate/5hEK1ToPWHVhE3Irje5KRq.mp4

Alternatively:

curl -X POST --data-urlencode ann_doc_id=541a0ebb1747d5305901b48a\
   <Base URI>/annotate --data-urlencode doc_url=http://localhost:8000/short_en.wav

process

This method is essentially the same as annotate with the following difference: this method accepts a JSON structure containing arbitraty arguments as http POST body contents. The whole structure is passed on to the service in the misc dictionnary.

The URL parameters which are required in the annotate are required as well for the process method. Hence one can submit a request in the same manner as for the annotate method yet also supply JSON contents in the body.

For example:

curl -X POST --data-urlencode ann_doc_id=541a0ebb1747d5305901b48a\
   <Base URI>/process --data-urlencode doc_url=http://localhost:8000/short_en.wav\
   --data-binary "@path/to/file"

In which the file contents would be for example:

{
    "task": "VideoOnly",
    "videoparams": {
        "codec": "h264",
        "bitrate": "1000k"
    },
    "dest": {
        "url": "ftp://ftp.server.ca/dest/tmp",
        "username": "myuser",
        "password": "my_password"
    }
}

status

To obtain the status or results of a given processing request

This method uses HTTP GET.

Parameters:

uuid:The identifier of a previous processing request.

Return value:

Returns a given response depending on the processing state. Consult the Status method page for the documentation of the response format.

Examples:

URL form:

<Base URI>/status?uuid=6547137e-cc2f-4008-b1eb-4ae8e898ce83

The Service Gateway can use authorization tokens to protect it’s routes from unwanted access. This is done with the use of JWT according to the deployment Default configuration file contents.