From 80896521ec24ed43ca66b69d445cfa9a6375863a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Euzenat?= <Jerome.Euzenat@inria.fr> Date: Sat, 5 Sep 2009 17:06:02 +0000 Subject: [PATCH] - improved the description according to the modified code --- html/rest.html | 435 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 333 insertions(+), 102 deletions(-) diff --git a/html/rest.html b/html/rest.html index 0aa00203..e3c09f3a 100644 --- a/html/rest.html +++ b/html/rest.html @@ -7,8 +7,9 @@ </head> <body bgcolor="#ffffff"> -<h1 style="text-align: center;">REST interface for the Alignment server</h1> +<h1 style="text-align: center;">Web service interface for the Alignment server</h1> +<h1>REST interface</h1> <p> The Alignment server provides a REST interface for accessing the functions available on the server. Each request is an URL starting @@ -22,121 +23,351 @@ The result of these requests are provided in XML. In the sequel, we describe the various request types. </p> -<h2>find</h2> -<p>Find alignments related to one or two ontologies.</p> -<p>URL: http://aserv.inrialpes.fr/rest/find?onto1=&onto2=& </p> -<p>Parameters:<br /> - <b>onto1</b> and <b>onto2</b> are ontology URIs. One of them may be not provided. -</p> - -<p>XML result :<br /> -<findResponse> -<id>3</id> -<in-reply-to>fr.inrialpes.exmo.align.service.Message@1cc3436</in-reply-to> -<alignmentList> -<alid>Alignment URI</alid> -... -</alignmentList> -</findResponse> -<p> +<h2>listalignments<a name="listalignments"></a></h2> +<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="fragment"> +<listalignmentsResponse> + <in-reply-to> MessageId </in-reply-to> + <alignmentList> + <alid> URI </alid> + ... + </alignmentList> +</listalignmentssResponse> +</div> +</p> +<h2>listmethods<a name="listmethods"></a></h2> +<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="fragment"> +<listmethodsResponse> + <in-reply-to> MessageId </in-reply-to> + <classList> + <classname> Classname </classname> + ... + </classList> +</listmethodsResponse> +</div> +</p> -<h2>listmethods</h2> -<p>Get the list of matching methods available on the server.</p> -<p>URL: http://aserv.inrialpes.fr/rest/listmethods?</p> -<p>XML result :<br /> - <listmethodsResponse> - <classList> - <method> Class Name </method> +<h2>listrenderers<a name="listrenderers"></a></h2> +<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="fragment"> +<listrenderersResponse> + <in-reply-to> MessageId </in-reply-to> + <classList> + <classname> Classname </classname> ... - </classList> - </listmethodsResponse> + </classList> +</listrenderersResponse> +</div> </p> -<h2>match</h2> -<p>Match two ontologies.</p> -<p>URL: http://aserv.inrialpes.fr/rest/match?onto1=&onto2=&method=&force=&</p> -<p>Parameters:<br /> - <b>onto1</b> and <b>onto2</b> are ontology URIs to be matched, - <br /> -<b>method</b> is a matching method from the list - obtained by http://aserv.inrialpes.fr/rest/listmethods?<br /> -The parameter <b>force</b> is optional and - "force=off" by default,<br /> -If "force=on", a new alignment will be - produced.<br /> -If "force=off", the server first tries to find - an existing alignment for the two ontologies. If no alignment is found a new alignment will be produced.</p> -<p>XML result :<br /> -<matchResponse> -<id>5</id><in-reply-to>fr.inrialpes.exmo.align.service.Message@b3869c</in-reply-to> -<alid> Found alignment URI</alid> -</matchResponse> -</p> - -<h2>retrieve</h2> -<p>Retrieve an alignment in a specific format.</p> -<p>URL: http://aserv.inrialpes.fr/rest/retrieve?id=&method=&</p> +<h2>listservices<a name="listservices"></a></h2> +<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="fragment"> +<listservicesResponse> + <in-reply-to> MessageId </in-reply-to> + <classList> + <classname> Classname </classname> + ... + </classList> +</listservicesResponse> +</div> +</p> + +<h2>listevaluators<a name="listevaluators"></a></h2> +<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="fragment"> +<listevaluatorsResponse> + <in-reply-to> MessageId </in-reply-to> + <classList> + <classname> Classname </classname> + ... + </classList> +</listevaluatorsResponse> +</div> +</p> + +<h2>match<a name="match"></a></h2> +<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>alid:</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="fragment"> +<matchResponse> + <id> MessageId </id> + <in-reply-to> MessageId </in-reply-to> + <alid> URI </alid> +</matchResponse> +</div> +</p> + +<h2>find<a name="find"></a></h2> +<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>id</b> is URI of alignment to be retrieved<br /> -<b>method</b> indicates the format in which the alignment will be + <b>onto1</b> and <b>onto2:</b> the URI of ontologies. One of them may be not provided. +</p> + +<p>Result:<br /> +<div class="fragment"> +<findResponse> + <id> MessageId </id> + <in-reply-to> messageId </in-reply-to> + <alignmentList> + <alid> URI </alid> + ... + </alignmentList> +</findResponse> +</div> +<p> + +<h2>retrieve<a name="retrieve"></a></h2> +<p>Retrieves an alignment in a specific format.</p> +<p>URL: http://aserv.inrialpes.fr/rest/ <b>retrieve</b> ? <b>alid</b> = + <URI> & <b>method</b> = <classname></p> +<p>Parameters: +<br /><b>alid:</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> + by <a href="#listrenderers">listrenderers</a> request. +</p> +<p>Result:<br /> +<div class="fragment"> +<retrieveResponse> + <result> + Alignment in required format + </result> +</retrieveResponse> +</div> +</p> -<p>Result :<br /> - Alignment in indicated format +<h2>trim<a name="trim"></a></h2> +<p>Trims an alignment with a threshhold.</p> +<p>URL: http://aserv.inrialpes.fr/rest/ <b>trim</b> ? <b>alid</b> = + <URI> & <b>threshold</b> = <float> & type = <label> </p> +<p>Parameters: +<br /><b>alid:</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="fragment"> +<trimResponse> + <id> MessageId </id> + <in-reply-to> MessageId </in-reply-to> + <alid> URI </alid> +</trimResponse> +</div> </p> -<h2>trim</h2> -<p>Trim an alignment with a threshhold.</p> -<p>URL: http://aserv.inrialpes.fr/rest/cut?id=&threshold=& </p> -<p>Parameters:<br /> - <b>id</b> is URI of alignment to be trimmed<br /> -<b>threshold</b> indicates a threshold for trimming</p> -<p>XML result :<br /> -<metadataResponse> - Metadata in RDF -</metadataResponse> +<h2>invert<a name="invert"></a></h2> +<p>Inverts an alignment.</p> +<p>URL: http://aserv.inrialpes.fr/rest/ <b>invert</b> ? <b>alid</b> = + <URI> </p> +<p>Parameters: +<br /><b>alid:</b> the URI of the alignment to be inverted. +</p> +<p>Result:<br /> +<div class="fragment"> +<invertResponse> + <id> MessageId </id> + <in-reply-to> MessageId </in-reply-to> + <alid> URI </alid> +</invertResponse> +</div> </p> -<h2>metadata</h2> -<p>Get metadata of an alignment, i.e., avoid downloading all correspondences.</p> -<p>URL: http://aserv.inrialpes.fr/rest/metadata?id= </p> -<p>Parameters:<br /> - <b>id</b> is URI of alignment</p> -<p>XML result :<br /> -<metadataResponse> - Metadata in RDF -</metadataResponse> +<h2>store<a name="store"></a></h2> +<p>Stores an alignment on the server.</p> +<p>URL: http://aserv.inrialpes.fr/rest/ <b>store</b> ? <b>alid</b> = <URI></p> +<p>Parameters: +<br /><b>alid:</b> the URI of the alignment to be stored. +</p> +<p>Result:<br /> +<div class="fragment"> +<storeResponse> + <id> MessageId </id> + <in-reply-to> MessageId </in-reply-to> + <alid> URI </alid> +</storeResponse> +</div> </p> -<h2>store</h2> -<p>Store an alignment on the server.</p> -<p>URL: http://aserv.inrialpes.fr/rest/store?id= </p> -<p>Parameters:<br /> - <b>id</b> is URI of alignment to be stored</p> -<p>XML result :<br /> -<storeResponse> -<id>11</id> -<in-reply-to> - fr.inrialpes.exmo.align.service.Message@11dee5e -</in-reply-to> -<alid> Alignment URI stored </alid> -</storeResponse> -</p> - -<h2>load</h2> -<p>Upload an alignment to the server.</p> -<p>URI: http://aserv.inrialpes.fr/rest/load? </p> -<p>Since this function uses POST request method, the content of alignment does not appear in URL. Therefore, this function should be called from a Java programme.</p> -<p>XML result :<br /> -<loadResponse> -<id>11</id> -<in-reply-to> - fr.inrialpes.exmo.align.service.Message@11dee5e -</in-reply-to> -<alid> Alignment URI loaded </alid> -</loadResponse> +<h2>load<a name="load"></a></h2> +<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></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. +</p> +<p>Result:<br /> +<div class="fragment"> +<loadResponse> + <id> MessageId </id> + <in-reply-to> MessageId </in-reply-to> + <alid> URI </alid> +</loadResponse> +</div> +</p> + +<h1>Unsupported features</h1> + +<p>These features may have been implemented and may become standard at + some point. For the moment, they are not. +</p> + +<h2>metadata<a name="metadata"></a></h2> +<p>Gets metadata of an alignment, i.e., avoid downloading all correspondences.</p> +<p>URL: http://aserv.inrialpes.fr/rest/ <b>metadata</b> ? <b>alid</b> = <URI></p> +<p>Parameters: +<br /><b>alid:</b> the URI of the alignment from which metadata is retrieved. +</p> +<p>Result:<br /> +<div class="fragment"> +<metadataResponse> + <in-reply-to> MessageId </in-reply-to> + Metadata in RDF +</metadataResponse> +</div> +</p> + +<h2>translate<a name="translate"></a></h2> +<p>Translates a message (resp. a query) with regard to an alignment.</p> +<p>URL: http://aserv.inrialpes.fr/rest/ <b>translate</b> ? <b>alid</b> = <URI></p> +<p>Parameters: +<br /><b>alid:</b> the URI of the alignment used for the translation. +</p> +<p>Result:<br /> +<div class="fragment"> +<translateResponse> + <in-reply-to> MessageId </in-reply-to> + Metadata in RDF +</translateResponse> +</div> +</p> + +<h2>align<a name="align"></a></h2> +<p>Matches two ontologies and directly returns the RDF rendering of the result.</p> +<p>URL: http://aserv.inrialpes.fr/rest/ <b>align</b> ? </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="fragment"> +<alignResponse> + <id> MessageId </id> + <in-reply-to> MessageId </in-reply-to> + <result> The alignment in RDF/XML </result> +</alignResponse> +</div> +</p> + +<h1>Note about the SOAP interface</h1> + +<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="fragment"> +<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> + +<h2>wsdl<a name="wsdl"></a></h2> + +<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> + +<h1>Changes introduced in version 4<a name="version4"></a></h1> + +<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>id</tt> for identying alignment ids is now replaced by <tt>alid</tt> (REST);</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 return <tt>in-reply-to</tt> and can + send <tt>id</tt> (REST);</li> +<li><tt>listevaluators</tt> has been added (REST & 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> -- GitLab