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

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.


http://alignapi.gforge.inria.fr/rest.html

$Id: rest.html 1221 2010-01-31 21:23:47Z euzenat $