Web service interface for the Alignment server

REST interface

The Alignment server provides a REST interface for accessing the functions available on the server (when launched with the -W switch). 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 color of the items correspond to the panel in the browser interface where these actions are found.

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

$ curl -L -H "Accept: text/xml" '<URL>'

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

Beware: URIs within the <URL> above should be URLEncoded. This is particularly true of '#' that do not pass through Java URL decoding.

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>

listnetworks

Gets the list of the ontology networks available on the server.

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

Parameters: none

Result:

<listnetworksResponse> <in-reply-to> MessageId </in-reply-to> <networkList> <onid> URI </onid> ... </networkList> </listnetworksResponse>

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>

matchnetwork

Compute alignments between each pairs of ontologies in a network.

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

Parameters:
id: the URI of the network 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.
sym: a boolean (default: false) requiring to compute the alignments in a symmetric fashion.
refl: a boolean (default: false) requiring to compute the alignments in a reflexive fashion, i.e., each ontology will be matched with itself.
paramnn and paramvn: the name and value of parameter n.

Note: the process is always asynchronous.

Result:

<matchnetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </matchnetworkResponse>

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>

get

Finds alignment(s) identified by names or pretty name.

URL: http://aserv.inrialpes.fr/rest/ get ? uri = <URI>

URL: http://aserv.inrialpes.fr/rest/ get ? desc = <String>

Parameters:
uri the URI of the alignment (does not need to have the server as prefix),
desc a string describing the alignment to be found in the Pretty attribute.

Result:

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

corresp

Finds the concepts corresponding to a concept in a particular alignment.

URL: http://aserv.inrialpes.fr/rest/ corresp ? id = <URI> & entity = <URI> & strict = <boolean>

Parameters:
id the URI of the alignment,
entity the URI of of the entity, and
strict a boolean (default: false) indicating (if present) that only equivalent entities are retrieved.

Result:

<correspResponse> <msgid> MessageId </msgid> <in-reply-to> messageId </in-reply-to> <entityList> <entity> URI </entity> ... </entityList> </correspResponse>

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> <alignment> Alignment in required format </alignment> </retrieveResponse>

printnetwork

Prints a network in RDF/XML format.

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

Parameters:
id: the URI of the network of ontology to print.

Result:

<printnetworkResponse> <network> Ontology network in RDF/XML </network> </printnetworkResponse>

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>

trimnetwork

Trims all the alignments in a network with a threshhold.

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

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

Result:

<trimnetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </trimnetworkResponse>

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>

invertnetwork

Inverts all alignments of a network of ontologies.

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

Parameters:
id: the URI of the network of ontologies to be inverted.

Result:

<invertnetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </invertnetworkResponse>

normalizenetwork

Normalises a network of ontologies, i.e., set exactly one alignment, eventually empty, between each pair of ontologies.

URL: http://aserv.inrialpes.fr/rest/ normalizenetwork ? id = <URI> & new = <boolean>

Parameters:
id: the URI of the network of ontologies to be normalised.
new: if true create a new network of ontologies (default: false).

Result:

<normalizenetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </normalizenetworkResponse>

denormalizenetwork

Suppress all empty alignments from a network of ontologies.

URL: http://aserv.inrialpes.fr/rest/ denormalizenetwork ? id = <URI> & new = <boolean>

Parameters:
id: the URI of the network of ontologies to be denormalised.
new: if true create a new network of ontologies (default: false).

Result:

<denormalizenetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </denormalizenetworkResponse>

closenetwork

Compute the closure a network of ontologies.

URL: http://aserv.inrialpes.fr/rest/ closenetwork ? id = <URI> & sym = <boolean> & trans = <boolean> & refl = <boolean>

Parameters:
id: the URI of the network of ontologies to be closed.
sym: indicates if the symmetric closure must be performed (default: false).
trans: indicates if the transitive closure must be performed (default: false).
refl: indicates if the reflexive closure must be performed (default: false).

Result:

<closenetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </closenetworkResponse>

eval

Evaluates an alignment on the server.

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

Parameters:
id: the URI of the alignment to be evaluated.
ref: the URI of the reference alignment.
method: the name of a evaluation method available on the server, see listevaluators (default: fr.inrialpes.exmo.align.impl.eval.PRecEvaluator).

Result:

<evalResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <result> Result of the evaluation </result> </evalResponse>

store

Stores an alignment in the persistent storage of 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>

storenetwork

Stores a network of ontologies in the persistent storage of the server.

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

Parameters:
id: the URI of the network of ontologies to be stored.

Result:

<storenetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </storenetworkResponse>

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> & force = <boolean>

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.
force: a boolean (default: false) which forces new registration of the alignment, even if the alignment is already loaded.

Result:

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

loadnetwork

Uploads a network of ontologies 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 network of ontologies is in the message content (e.g., a loadfile java script, see here).

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

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

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

Result:

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

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> <alignment> Metadata in RDF </alignment> </metadataResponse>

translate

Translates a query with regard to an alignment.

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

Parameters:
id: the URI of the alignment used for the translation.
query: the query to be translated (URL encoded).

Result:

<translateResponse> <in-reply-to> MessageId </in-reply-to> <message> The translated query </message> </translateResponse>

Potential other features

Here are some feature that could eventually be implemented if someone has a need for them.

Getting metadata by keys (one by one).

findNetworksWithOntologies for finding network containing particular ontologies.

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: https://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.

https://moex.gitlabpages.inria.fr/alignapi/rest.html