Newer
Older
<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 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
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 result of these requests are provided in XML.
In the sequel, we describe the various request types.
</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>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>
</listrenderersResponse>
</div>
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
<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>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>
<p>Result:<br />
<div class="fragment">
<retrieveResponse>
<result>
Alignment in required format
</result>
</retrieveResponse>
</div>
</p>
<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>
<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>
<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>
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
<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>