Alignment API: REST interface

# Web service interface for the Alignment server

# REST interface

The Alignment server provides a REST interface for accessing the functions available on the server. Each request is an URL starting with a prefix, e.g., http://aserv.inrialpes.fr/rest/. The request type is identified by a string followed by a question mark, e.g., match?, and parameters are given in the classical URL syntax, e.g., debug=true&level=1.

The result of these requests are provided in XML. In the sequel, we describe the various request types. They can be obtained by:

$ curl -H "Content-Type: text/xml" <URL>

The `msgid` and `in-reply-to` elements are not compulsory and may not be present in messages.

## listalignments

Gets the list of the alignments available on the server.

URL: http://aserv.inrialpes.fr/rest/ listalignments ?

Parameters: none

Result:

<listalignmentsResponse> <in-reply-to> MessageId </in-reply-to> <alignmentList> <alid> URI </alid> ... </alignmentList> </listalignmentssResponse>

## listmethods

Gets the list of matching methods available on the server.

URL: http://aserv.inrialpes.fr/rest/ listmethods ?

Parameters: none

Result:

<listmethodsResponse> <in-reply-to> MessageId </in-reply-to> <classList> <classname> Classname </classname> ... </classList> </listmethodsResponse>

## listrenderers

Gets the list of renderer methods available on the server.

URL: http://aserv.inrialpes.fr/rest/ listrenderers ?

Parameters: none

Result:

<listrenderersResponse> <in-reply-to> MessageId </in-reply-to> <classList> <classname> Classname </classname> ... </classList> </listrenderersResponse>

## listservices

Gets the list of communication services available (and running) on the server.

URL: http://aserv.inrialpes.fr/rest/ listservices ?

Parameters: none

Result:

<listservicesResponse> <in-reply-to> MessageId </in-reply-to> <classList> <classname> Classname </classname> ... </classList> </listservicesResponse>

## listevaluators

Gets the list of evauators available on the server.

URL: http://aserv.inrialpes.fr/rest/ listevaluators ?

Parameters: none

Result:

<listevaluatorsResponse> <in-reply-to> MessageId </in-reply-to> <classList> <classname> Classname </classname> ... </classList> </listevaluatorsResponse>

## match

Matches two ontologies.

URL: http://aserv.inrialpes.fr/rest/ match ? onto1 = <URI> & onto2 = <URI> & method = <classname> & force = <boolean>

Parameters:
onto1 and onto2: the URLs of ontologies to be matched,
method: the name of a matching method available on the server, see listmethods (default: fr.inrialpes.exmo.align.impl.method.StringDistAlignment).
force: a boolean (default: false) which forces the server to create a new alignment even if one is already available.
otherwise, the server first tries to find an existing alignment for the two ontologies. If no alignment is found a new alignment will be produced.
async: a boolean (default: false) requiring the matching to be asynchronous, in which case the server immediately returns the URI that will be assigned to the resulting alignment. The alignment will be available at a later moment. By default, matching is synchronous, i.e., the server answers only once the alignment process has returned an alignment.
pretty: a string that will name the resulting alignment.
id: the URI of an initial alignment.
paramnn and paramvn: the name and value of parameter n.

Result:

<matchResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </matchResponse>

## find

Finds alignments related to one or two ontologies.

URL: http://aserv.inrialpes.fr/rest/ find ? onto1 = <URI> & onto2 = <URI>

Parameters:
onto1 and onto2: the URI of ontologies. One of them may be not provided.

Result:

<findResponse> <msgid> MessageId </msgid> <in-reply-to> messageId </in-reply-to> <alignmentList> <alid> URI </alid> ... </alignmentList> </findResponse>

## retrieve

Retrieves an alignment in a specific format.

URL: http://aserv.inrialpes.fr/rest/ retrieve ? id = <URI> & method = <classname>

Parameters:
id: the URI of the alignment to be retrieved.
method: indicates the format in which the alignment will be serialised this is a classname taken from those provided by listrenderers request.

Result:

<retrieveResponse> <result> Alignment in required format </result> </retrieveResponse>

## trim

Trims an alignment with a threshhold.

URL: http://aserv.inrialpes.fr/rest/ trim ? id = <URI> & threshold = <float> & type = <label>

Parameters:
id: the URI of the alignment to be trimmed.
threshold: the threshold for trimming.
type: the method used for trimming (values: hard, perc, best, span, prop; default: hard).

Result:

<trimResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </trimResponse>

## invert

Inverts an alignment.

URL: http://aserv.inrialpes.fr/rest/ invert ? id = <URI>

Parameters:
id: the URI of the alignment to be inverted.

Result:

<invertResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </invertResponse>

## store

Stores an alignment on the server.

URL: http://aserv.inrialpes.fr/rest/ store ? id = <URI>

Parameters:
id: the URI of the alignment to be stored.

Result:

<storeResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </storeResponse>

## load

Uploads an alignment to the server.

This function can work in two ways: either with a url parameter which contains a publicly accessible URL that the server will use for uploading the file, or by using a POST request method, in which the alignment is in the message content (e.g., a loadfile java script, see here).

URI: http://aserv.inrialpes.fr/rest/ load ? url = <URL> & pretty = <string>

or

URI: http://aserv.inrialpes.fr/rest/ load ? pretty = <string>

Parameters:
url: the accessible URL where to find the alignment to upload.
pretty: a string that will name the resulting alignment.

Result:

<loadResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </loadResponse>

# Unsupported features

These features may have been implemented and may become standard at some point. For the moment, they are not.

## metadata

Gets metadata of an alignment, i.e., avoid downloading all correspondences.

URL: http://aserv.inrialpes.fr/rest/ metadata ? id = <URI>

Parameters:
id: the URI of the alignment from which metadata is retrieved.

Result:

<metadataResponse> <in-reply-to> MessageId </in-reply-to> Metadata in RDF </metadataResponse>

## translate

Translates a message (resp. a query) with regard to an alignment.

URL: http://aserv.inrialpes.fr/rest/ translate ? id = <URI>

Parameters:
id: the URI of the alignment used for the translation.

Result:

<translateResponse> <in-reply-to> MessageId </in-reply-to> Metadata in RDF </translateResponse>

## align

Matches two ontologies and directly returns the RDF rendering of the result.

URL: http://aserv.inrialpes.fr/rest/ align ?

Parameters:
onto1 and onto2: the URLs or URIs of the ontology to be matched.

Result: the alignment in RDF/XML.

<alignResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <result> The alignment in RDF/XML </result> </alignResponse>

# Note about the SOAP interface

As of version 4.0 of the Alignment API, the SOAP and REST interface are aligned: the arguments are the same and the message answers are the same.

The SOAP protocol is described in a WSDL file available from the server through the wsdl request.

Form of requests:

... and answers:
<SOAP-ENV:Envelope xmlns='http://exmo.inrialpes.fr/align/service' xml:base='http://exmo.inrialpes.fr/align/service' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' xmlns:xsi='http://www.w3.org/1999/XMLSchema-instance' xmlns:xsd='http://www.w3.org/1999/XMLSchema'> <SOAP-ENV:Body> ... </SOAP-ENV:Body> </SOAP-ENV:Envelope>

## wsdl

Gets the Web Service Description Language description of the SOAP interface.

URL: http://aserv.inrialpes.fr/ wsdl ?

Parameters: none

Result: WSDL file in XML

# Changes introduced in version 4

- The content of `classList` is now `classname` (instead of `method`, `service`, or `renderer`) (REST & SOAP);
- `cut` is now `trim` (REST & SOAP);
- `method` in `trim` is now `type` (REST & SOAP);
- All primitives may return `in-reply-to` and may send `msgid` (REST);
- `listevaluators` has been added (REST & SOAP);
- The `alid` parameter for identying alignment ids in requests is now replaced by `id` (SOAP);
- The `id` parameter for identying messages is now replaced by `msgid` (SOAP);

In the examples/wservice directory, there is a sample application, AlignmentClient, that shows how to implement a web service client for the Alignement server. It is able to work with both the REST and the SOAP interface.