<html> <head> <title>Alignment API: REST interface</title> <!--style type="text/css">@import url(style.css);</style--> <link rel="stylesheet" type="text/css" href="base.css" /> <link rel="stylesheet" type="text/css" href="style.css" /> </head> <body bgcolor="#ffffff"> <h1>Web service interface for the Alignment server</h1> <h2>REST interface</h2> <p> 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. </p> <p> The color of the items correspond to the panel in the browser interface where these actions are found. </p> <p> 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: <div class="terminal"> $ curl -L -H "Accept: text/xml" '<URL>' </div> </p> <p> The <tt>msgid</tt> and <tt>in-reply-to</tt> elements are not compulsory and may not be present in messages. </p> <p style="background-color: yellow;"> Beware: URIs within the <URL> above should be URLEncoded. This is particularly true of '#' that do not pass through Java URL decoding. </p> <h3><span style="background-color: lightblue;">listalignments</span><a name="listalignments"></a></h3> <p>Gets the list of the alignments available on the server.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>listalignments</b> ?</p> <p>Parameters: none</p> <p>Result:<br /> <div class="xml"> <listalignmentsResponse> <in-reply-to> MessageId </in-reply-to> <alignmentList> <alid> URI </alid> ... </alignmentList> </listalignmentssResponse> </div> </p> <h3><span style="background-color: lightgreen;">listnetworks</span><a name="listnetworkss"></a></h3> <p>Gets the list of the ontology networks available on the server.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>listnetworks</b> ?</p> <p>Parameters: none</p> <p>Result:<br /> <div class="xml"> <listnetworksResponse> <in-reply-to> MessageId </in-reply-to> <networkList> <onid> URI </onid> ... </networkList> </listnetworksResponse> </div> </p> <h3><span style="background-color: lightpink;">listmethods</span><a name="listmethods"></a></h3> <p>Gets the list of matching methods available on the server.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>listmethods</b> ?</p> <p>Parameters: none</p> <p>Result:<br /> <div class="xml"> <listmethodsResponse> <in-reply-to> MessageId </in-reply-to> <classList> <classname> Classname </classname> ... </classList> </listmethodsResponse> </div> </p> <h3><span style="background-color: lightpink;">listrenderers</span><a name="listrenderers"></a></h3> <p>Gets the list of renderer methods available on the server.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>listrenderers</b> ?</p> <p>Parameters: none</p> <p>Result:<br /> <div class="xml"> <listrenderersResponse> <in-reply-to> MessageId </in-reply-to> <classList> <classname> Classname </classname> ... </classList> </listrenderersResponse> </div> </p> <h3><span style="background-color: lightpink;">listservices</span><a name="listservices"></a></h3> <p>Gets the list of communication services available (and running) on the server.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>listservices</b> ?</p> <p>Parameters: none</p> <p>Result:<br /> <div class="xml"> <listservicesResponse> <in-reply-to> MessageId </in-reply-to> <classList> <classname> Classname </classname> ... </classList> </listservicesResponse> </div> </p> <h3><span style="background-color: lightpink;">listevaluators</span><a name="listevaluators"></a></h3> <p>Gets the list of evauators available on the server.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>listevaluators</b> ?</p> <p>Parameters: none</p> <p>Result:<br /> <div class="xml"> <listevaluatorsResponse> <in-reply-to> MessageId </in-reply-to> <classList> <classname> Classname </classname> ... </classList> </listevaluatorsResponse> </div> </p> <h3><span style="background-color: lightblue;">match</span><a name="match"></a></h3> <p>Matches two ontologies.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>match</b> ? <b>onto1</b> = <URI> & <b>onto2</b> = <URI> & method = <classname> & force = <boolean></p> <p>Parameters: <br /><b>onto1</b> and <b>onto2:</b> the URLs of ontologies to be matched, <br /><b>method:</b> the name of a matching method available on the server, see <a href="#listmethods">listmethods</a> (default: fr.inrialpes.exmo.align.impl.method.StringDistAlignment). <br /><b>force:</b> a boolean (default: false) which forces the server to create a new alignment even if one is already available.<br /> 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. <br /><b>async:</b> 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. <br /><b>pretty:</b> a string that will name the resulting alignment. <br /><b>id:</b> the URI of an initial alignment. <br /><b>paramn<i>n</i></b> and <b>paramv<i>n</i>:</b> the name and value of parameter <i>n</i>. </p> <p>Result:<br /> <div class="xml"> <matchResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </matchResponse> </div> </p> <h3><span style="background-color: lightgreen;">matchnetwork</span><a name="match"></a></h3> <p>Compute alignments between each pairs of ontologies in a network.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>matchnetwork</b> ? <b>id</b> = <URI> & method = <classname> & force = <boolean></p> <p>Parameters: <br /><b>id:</b> the URI of the network to be matched, <br /><b>method:</b> the name of a matching method available on the server, see <a href="#listmethods">listmethods</a> (default: fr.inrialpes.exmo.align.impl.method.StringDistAlignment). <br /><b>force:</b> a boolean (default: false) which forces the server to create a new alignment even if one is already available.<br /> 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. <br /><b>sym:</b> a boolean (default: false) requiring to compute the alignments in a symmetric fashion. <br /><b>refl:</b> a boolean (default: false) requiring to compute the alignments in a reflexive fashion, i.e., each ontology will be matched with itself. <br /><b>paramn<i>n</i></b> and <b>paramv<i>n</i>:</b> the name and value of parameter <i>n</i>. </p> <p>Note: the process is always asynchronous. </p> <p>Result:<br /> <div class="xml"> <matchnetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </matchnetworkResponse> </div> </p> <h3><span style="background-color: lightblue;">find</span><a name="find"></a></h3> <p>Finds alignments related to one or two ontologies.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>find</b> ? <b>onto1</b> = <URI> & <b>onto2</b> = <URI></p> <p>Parameters:<br /> <b>onto1</b> and <b>onto2:</b> the URI of ontologies. One of them may be not provided. </p> <p>Result:<br /> <div class="xml"> <findResponse> <msgid> MessageId </msgid> <in-reply-to> messageId </in-reply-to> <alignmentList> <alid> URI </alid> ... </alignmentList> </findResponse> </div> <p> <h3><span style="background-color: lightblue;">get</span><a name="get"></a></h3> <p>Finds alignment(s) identified by names or pretty name.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>get</b> ? <b>uri</b> = <URI> </p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>get</b> ? <b>desc</b> = <String> </p> <p>Parameters:<br /> <b>uri</b> the URI of the alignment (does not need to have the server as prefix),<br /> <b>desc</b> a string describing the alignment to be found in the Pretty attribute. </p> <p>Result:<br /> <div class="xml"> <getResponse> <msgid> MessageId </msgid> <in-reply-to> messageId </in-reply-to> <alignmentList> <alid> URI </alid> ... </alignmentList> </getResponse> </div> <p> <h3><span style="background-color: lightblue;">corresp</span><a name="corresp"></a></h3> <p>Finds the concepts corresponding to a concept in a particular alignment.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>corresp</b> ? <b>id</b> = <URI> & <b>entity</b> = <URI> & strict = <boolean></p> <p>Parameters:<br /> <b>id</b> the URI of the alignment,<br /> <b>entity</b> the URI of of the entity, and<br /> <b>strict</b> a boolean (default: false) indicating (if present) that only equivalent entities are retrieved. </p> <p>Result:<br /> <div class="xml"> <correspResponse> <msgid> MessageId </msgid> <in-reply-to> messageId </in-reply-to> <entityList> <entity> URI </entity> ... </entityList> </correspResponse> </div> <p> <h3><span style="background-color: lightblue;">retrieve</span><a name="retrieve"></a></h3> <p>Retrieves an alignment in a specific format.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>retrieve</b> ? <b>id</b> = <URI> & <b>method</b> = <classname></p> <p>Parameters: <br /><b>id:</b> the URI of the alignment to be retrieved. <br /><b>method:</b> indicates the format in which the alignment will be serialised this is a classname taken from those provided by <a href="#listrenderers">listrenderers</a> request. </p> <p>Result:<br /> <div class="xml"> <retrieveResponse> <alignment> Alignment in required format </alignment> </retrieveResponse> </div> </p> <h3><span style="background-color: lightgreen;">printnetwork</span><a name="printnetwork"></a></h3> <p>Prints a network in RDF/XML format.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>printnetwork</b> ? <b>id</b> = <URI></p> <p>Parameters: <br /><b>id:</b> the URI of the network of ontology to print. </p> <p>Result:<br /> <div class="xml"> <printnetworkResponse> <network> Ontology network in RDF/XML </network> </printnetworkResponse> </div> </p> <h3><span style="background-color: lightblue;">trim</span><a name="trim"></a></h3> <p>Trims an alignment with a threshhold.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>trim</b> ? <b>id</b> = <URI> & <b>threshold</b> = <float> & type = <label> </p> <p>Parameters: <br /><b>id:</b> the URI of the alignment to be trimmed. <br /><b>threshold:</b> the threshold for trimming. <br /><b>type:</b> the method used for trimming (values: hard, perc, best, span, prop; default: hard). </p> <p>Result:<br /> <div class="xml"> <trimResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </trimResponse> </div> </p> <h3><span style="background-color: lightgreen;">trimnetwork</span><a name="trim"></a></h3> <p>Trims all the alignments in a network with a threshhold.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>trimnetwork</b> ? <b>id</b> = <URI> & <b>threshold</b> = <float> & type = <label> </p> <p>Parameters: <br /><b>id:</b> the URI of the network of ontologies to be trimmed. <br /><b>threshold:</b> the threshold for trimming. <br /><b>type:</b> the method used for trimming (values: hard, perc, best, span, prop; default: hard). </p> <p>Result:<br /> <div class="xml"> <trimnetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </trimnetworkResponse> </div> </p> <h3><span style="background-color: lightblue;">invert</span><a name="invert"></a></h3> <p>Inverts an alignment.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>invert</b> ? <b>id</b> = <URI> </p> <p>Parameters: <br /><b>id:</b> the URI of the alignment to be inverted. </p> <p>Result:<br /> <div class="xml"> <invertResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </invertResponse> </div> </p> <h3><span style="background-color: lightgreen;">invertnetwork</span><a name="invert"></a></h3> <p>Inverts all alignments of a network of ontologies.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>invertnetwork</b> ? <b>id</b> = <URI> </p> <p>Parameters: <br /><b>id:</b> the URI of the network of ontologies to be inverted. </p> <p>Result:<br /> <div class="xml"> <invertnetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </invertnetworkResponse> </div> </p> <h3><span style="background-color: lightgreen;">normalizenetwork</span><a name="normalize"></a></h3> <p>Normalises a network of ontologies, i.e., set exactly one alignment, eventually empty, between each pair of ontologies.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>normalizenetwork</b> ? <b>id</b> = <URI> & new = <boolean> </p> <p>Parameters: <br /><b>id:</b> the URI of the network of ontologies to be normalised. <br /><b>new:</b> if true create a new network of ontologies (default: false). </p> <p>Result:<br /> <div class="xml"> <normalizenetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </normalizenetworkResponse> </div> </p> <h3><span style="background-color: lightgreen;">denormalizenetwork</span><a name="normalize"></a></h3> <p>Suppress all empty alignments from a network of ontologies.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>denormalizenetwork</b> ? <b>id</b> = <URI> & new = <boolean> </p> <p>Parameters: <br /><b>id:</b> the URI of the network of ontologies to be denormalised. <br /><b>new:</b> if true create a new network of ontologies (default: false). </p> <p>Result:<br /> <div class="xml"> <denormalizenetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </denormalizenetworkResponse> </div> </p> <h3><span style="background-color: lightgreen;">closenetwork</span><a name="close"></a></h3> <p>Compute the closure a network of ontologies.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>closenetwork</b> ? <b>id</b> = <URI> & sym = <boolean> & trans = <boolean> & refl = <boolean> </p> <p>Parameters: <br /><b>id:</b> the URI of the network of ontologies to be closed. <br /><b>sym:</b> indicates if the symmetric closure must be performed (default: false). <br /><b>trans:</b> indicates if the transitive closure must be performed (default: false). <br /><b>refl:</b> indicates if the reflexive closure must be performed (default: false). </p> <p>Result:<br /> <div class="xml"> <closenetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </closenetworkResponse> </div> </p> <h3><span style="background-color: lightblue;">eval</span><a name="eval"></a></h3> <p>Evaluates an alignment on the server.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>eval</b> ? <b>id</b> = <URI> & <b>ref</b> = <URI> & method = <classname></p> <p>Parameters: <br /><b>id:</b> the URI of the alignment to be evaluated. <br /><b>ref:</b> the URI of the reference alignment. <br /><b>method:</b> the name of a evaluation method available on the server, see <a href="#listevaluators">listevaluators</a> (default: fr.inrialpes.exmo.align.impl.eval.PRecEvaluator). </p> <p>Result:<br /> <div class="xml"> <evalResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <result> Result of the evaluation </result> </evalResponse> </div> </p> <h3><span style="background-color: lightblue;">store</span><a name="store"></a></h3> <p>Stores an alignment in the persistent storage of the server.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>store</b> ? <b>id</b> = <URI></p> <p>Parameters: <br /><b>id:</b> the URI of the alignment to be stored. </p> <p>Result:<br /> <div class="xml"> <storeResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </storeResponse> </div> </p> <h3><span style="background-color: lightgreen;">storenetwork</span><a name="store"></a></h3> <p>Stores a network of ontologies in the persistent storage of the server.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>storenetwork</b> ? <b>id</b> = <URI></p> <p>Parameters: <br /><b>id:</b> the URI of the network of ontologies to be stored. </p> <p>Result:<br /> <div class="xml"> <storenetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <onid> URI </onid> </storenetworkResponse> </div> </p> <h3><span style="background-color: lightblue;">load</span><a name="load"></a></h3> <p>Uploads an alignment to the server.</p> <p> 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 <a href="http://aserv.inrialpes.fr/html/prmload?">here</a>).</p> <p>URI: http://aserv.inrialpes.fr/rest/ <b>load</b> ? <b>url</b> = <URL> & pretty = <string> & force = <boolean></p> or <p>URI: http://aserv.inrialpes.fr/rest/ <b>load</b> ? pretty = <string></p> <p>Parameters: <br /><b>url:</b> the accessible URL where to find the alignment to upload. <br /><b>pretty:</b> a string that will name the resulting alignment. <br /><b>force:</b> a boolean (default: false) which forces new registration of the alignment, even if the alignment is already loaded. </p> <p>Result:<br /> <div class="xml"> <loadResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </loadResponse> </div> </p> <h3><span style="background-color: lightgreen;">loadnetwork</span><a name="load"></a></h3> <p>Uploads a network of ontologies to the server.</p> <p> 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 <a href="http://aserv.inrialpes.fr/html/prmload?">here</a>).</p> <p>URI: http://aserv.inrialpes.fr/rest/ <b>loadnetwork</b> ? <b>url</b> = <URL> & pretty = <string></p> or <p>URI: http://aserv.inrialpes.fr/rest/ <b>loadnetwork</b> ? pretty = <string></p> <p>Parameters: <br /><b>url:</b> the accessible URL where to find the alignment to upload. <br /><b>pretty:</b> a string that will name the resulting alignment. </p> <p>Result:<br /> <div class="xml"> <loadnetworkResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <alid> URI </alid> </loadnetworkResponse> </div> </p> <h3><span style="background-color: lightblue;">metadata</span><a name="metadata"></a></h3> <p>Gets metadata of an alignment, i.e., avoid downloading all correspondences.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>metadata</b> ? <b>id</b> = <URI></p> <p>Parameters: <br /><b>id:</b> the URI of the alignment from which metadata is retrieved. </p> <p>Result:<br /> <div class="xml"> <metadataResponse> <in-reply-to> MessageId </in-reply-to> <alignment> Metadata in RDF </alignment> </metadataResponse> </div> </p> <h3><span style="background-color: lightblue;">translate</span><a name="translate"></a></h3> <p>Translates a query with regard to an alignment.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>translate</b> ? <b>id</b> = <URI> & <b>query</b> = <SPARQL></p> <p>Parameters: <br /><b>id:</b> the URI of the alignment used for the translation. <br /><b>query:</b> the query to be translated (URL encoded). </p> <p>Result:<br /> <div class="xml"> <translateResponse> <in-reply-to> MessageId </in-reply-to> <message> The translated query </message> </translateResponse> </div> </p> <!--h3><span style="background-color: lightblue;">align</span><a name="align"></a></h3> <p>Matches two ontologies and directly returns the RDF rendering of the result.</p> <p>URL: http://aserv.inrialpes.fr/rest/ <b>align</b> ? <b>onto1</b> = <URI> & <b>onto2</b> = <URI> </p> <p>Parameters: <br /><b>onto1</b> and <b>onto2:</b> the URLs or URIs of the ontology to be matched. </p> <p>Result: the alignment in RDF/XML. <div class="xml"> <alignResponse> <msgid> MessageId </msgid> <in-reply-to> MessageId </in-reply-to> <result> The alignment in RDF/XML </result> </alignResponse> </div> </p--> <!--h2>Unsupported features</h2> <p>These features may have been implemented and may become standard at some point. For the moment, they are not. </p--> <h2>Potential other features</h2> <p>Here are some feature that could eventually be implemented if someone has a need for them.</p> <p>Getting metadata by keys (one by one).</p> <p>findNetworksWithOntologies for finding network containing particular ontologies.</p> <h2>Note about the SOAP interface</h2> <p> 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. </p> <p> The SOAP protocol is described in a WSDL file available from the server through the wsdl request. </p> <p> Form of requests: <pre> </pre>... and answers: <div class="xml"> <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> </div> </p> <h3><span style="background-color: lightpink;">wsdl</span><a name="wsdl"></a></h3> <p>Gets the Web Service Description Language description of the SOAP interface.</p> <p>URL: <a href="http://aserv.inrialpes.fr/wsdl?">http://aserv.inrialpes.fr/ <b>wsdl</b> ?</a> </p> <p>Parameters: none</p> <p>Result: WSDL file in XML </p> <h2>Changes introduced in version 4<a name="version4"></a></h2> <ul> <li>The content of <tt>classList</tt> is now <tt>classname</tt> (instead of <tt>method</tt>, <tt>service</tt>, or <tt>renderer</tt>) (REST & SOAP);</li> <li><tt>cut</tt> is now <tt>trim</tt> (REST & SOAP);</li> <li><tt>method</tt> in <tt>trim</tt> is now <tt>type</tt> (REST & SOAP);</li> <li>All primitives may return <tt>in-reply-to</tt> and may send <tt>msgid</tt> (REST);</li> <li><tt>listevaluators</tt> has been added (REST & SOAP);</li> <li>The <tt>alid</tt> parameter for identying alignment ids in requests is now replaced by <tt>id</tt> (SOAP);</li> <li>The <tt>id</tt> parameter for identying messages is now replaced by <tt>msgid</tt> (SOAP);</li> </ul> <p> 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. </p> <address> <small> <hr /> <center>http://alignapi.gforge.inria.fr/rest.html</center> <hr /> $Id$ </small> </body> </html>