OPTIONS in JAQPOT

From OpenTox
Jump to: navigation, search

The OPTIONS method in OpenTox web services exposes rigorously the way a web service should be consumed thus providing auto-generated documentation and machine-readable guidelines to an HTTP client regarding the consumption of a service. An HTTP client eventually would now that it is allowed to perform - for instance - a GET on a model without providing an authentication token but a POST would require authentication.

The OPTIONS HTTP method in OpenTox

One of the prime attributes of the REST architecture is that is decouples clients from servers since the latter should provide a uniform interface which oughts to be transparent and well documented. To this end, servers have to provide (machine readable) guidelines to the clients regarding all details about the service invocations. Such information include supported media types, expected status codes, possible input parameters (either as POSTed within a form, included in the web address as URL-parameters or contained in the Header of the request), information about the implemented methods and much more; always followed by proper (human readable) annotations.

The establishment of a REST ontology for OpenTox is expected to:

  1. Enhance the server-client communication providing information to the client about possible exceptions that might occur.
  2. Makes possible the automated creation of clients for OpenTox web services (The user provides an OpenTox URL and a web interface appears, providing all REST-related information about the service plus a web form for it's consumption)
  3. Human readable documentation about the service can be retrieved and made available in HTML, PDF or other user friendly formats.

OpenTox web services provide guidelines to the client specifying the way they are supposed to be consumed. Following the OpenTox pattern, an OPTIONS request to a URL returns an RDF/XML document. A cURL command line request would look like that:

curl -X OPTIONS -H Accept:application/rdf+xml http://opentox.service.org:1234/some/service

The following RDF/XML was returned by a locally running JAQPOT3 over the URL http://alphaville:8080/model/95907284-da77-44b7-968f-6c46eaf87c65. You can experiment on your own using the deployed instance of JAQPOT3 at opentox.ntua.gr:8080. Here is an example cURL call:

curl -X OPTIONS -H Accept:application/rdf+xml http://opentox.ntua.gr:8080/model/1

Using your web browser, you can append the following to any JAQPOT3 URL to get the options of this resource (example):

?media=application/rdf%2Bxml&method=OPTIONS

An example representation returned by OPTIONS is:

<rdf:RDF
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    ... > 

  <rdf:Description rdf:about="http://alphaville:8080/model/95907284-da77-44b7-968f-6c46eaf87c65">
    <otrs:hasRESTOperation rdf:nodeID="A0"/>
    <rdf:type rdf:resource="http://www.opentox.org/api/1.1#OpenToxResource"/>
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#RESTOperation"/>
  </rdf:Description>

  <rdf:Description rdf:nodeID="A1">
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#STATUS_401"/>
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#HTTPStatus"/>
  </rdf:Description>

  <rdf:Description rdf:nodeID="A0">
    <otrs:resource rdf:resource="http://alphaville:8080/model/95907284-da77-44b7-968f-6c46eaf87c65"/>
    <otrs:hasMedia rdf:nodeID="A2"/>
    <otrs:hasHTTPStatus rdf:nodeID="A3"/>
    <otrs:hasHTTPStatus rdf:nodeID="A4"/>
    <otrs:hasHTTPStatus rdf:nodeID="A5"/>
    <otrs:hasHTTPStatus rdf:nodeID="A1"/>
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#RESTOperation"/>
  </rdf:Description>

  <rdf:Description rdf:nodeID="A3">
    <dc:description rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
The model was found in the database and its representation in the prefered MIME type is returned to the client.
    </dc:description>
    <dc:title rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Success</dc:title>
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#STATUS_200"/>
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#HTTPStatus"/>
  </rdf:Description>

  <rdf:Description rdf:nodeID="A5">
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#STATUS_403"/>
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#HTTPStatus"/>
  </rdf:Description>

  <rdf:Description rdf:nodeID="A4">
    <rdfs:comment rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
     You can have a complete list of the available models at http://alphaville:8080/model
    </rdfs:comment>
    <dc:description rdf:datatype="http://www.w3.org/2001/XMLSchema#string">The model was not found in the database</dc:description>
    <dc:title rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Not Found</dc:title>
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#STATUS_404"/>
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#HTTPStatus"/>
  </rdf:Description>

  <rdf:Description rdf:nodeID="A2">
    <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#mime_text_uri_list"/>
  </rdf:Description>
</rdf:RDF>
OpenTox components.
OpenTox Components

A quick look at the above RDF/XML reveals the way the service expects the client to act in order to make use of it. It defines the various status codes that are expected. For example the following excerpt defines a successful GET on the resource explaining that the expected status code is 200:

<rdf:Description rdf:nodeID="A3">
 <dc:description rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
  The model was found in the database and its representation in the prefered 
  MIME type is returned to the client.</dc:description>
  <dc:title rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Success</dc:title>
  <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#STATUS_200"/>
  <rdf:type rdf:resource="http://opentox.org/opentox-rest.owl#HTTPStatus"/>
</rdf:Description>


Templated REST documentation in ToxOtis

The defining ontology can be found at the OpeTox collaborative Protege and its latest version is attached. If you use Java for your web services, you can consider using ToxOtis (version 0.4.12.2 or later) for the creation of REST specifications for your services. Here is an example using ToxOtis CORE:

ServiceRestDocumentation doc = new ServiceRestDocumentation(new Task(new VRI(“ http://myserver.com/task/1” )));
RestOperation delete = new RestOperation();
delete.addHttpStatusCodes(
new HttpStatus(OTRestClasses.STATUS_200()).setMeta(new MetaInfoImpl().addTitle("Success").
addDescription("The task was successfully deleted from the database").
addComment("The status code 200 is returned in any case of successful deletion but excluding the "
+ "case where the underlying task was not found in the database")),
new HttpStatus(OTRestClasses.STATUS_404()).setMeta(new MetaInfoImpl().addTitle("Not Found").
addDescription("The task was not found in the database")),
new HttpStatus(OTRestClasses.STATUS_403()),
new HttpStatus(OTRestClasses.STATUS_401()));
delete.setMethod(MethodsEnum.DELETE);
delete.addOntologicalClasses(
OTRestClasses.DELETE_Task(), OTRestClasses.OperationTask(), OTRestClasses.OperationNoResult());
delete.getMeta().addDescription("Cancels a running task.");
delete.setProtectedResource(false);
RestOperation get = new RestOperation();
get.addHttpStatusCodes(
new HttpStatus(OTRestClasses.STATUS_200()).setMeta(new MetaInfoImpl().addTitle("Success").
addDescription("The task is successfully retrieved from the database and has completed redirecting to the result "
+ "of the calculation")),
new HttpStatus(OTRestClasses.STATUS_202()).setMeta(new MetaInfoImpl().addTitle("Success").
addDescription("The task is successfully retrieved from the database and is still running/processing")),
new HttpStatus(OTRestClasses.STATUS_201()).setMeta(new MetaInfoImpl().addTitle("Success").
addDescription("The task is successfully retrieved from the database has completed its own part of
+ “ the overall work but redirect to some other task on some other server")),
new HttpStatus(OTRestClasses.STATUS_404()).setMeta(new MetaInfoImpl().addTitle("Not Found").
addDescription("The task was successfully deleted from the database")),
new HttpStatus(OTRestClasses.STATUS_403()),
new HttpStatus(OTRestClasses.STATUS_401()));
get.addUrlParameter("media", true, XSDDatatype.XSDstring);
get.addUrlParameter("method", true, XSDDatatype.XSDstring);
doc.addRestOperations(delete, get);


References

  1. http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.2 [OPTIONS method]
  2. http://opentox.org/dev/ontology/collaborative_protege [OpenTox Collaborative Protégé]
  3. https://github.com/alphaville/ToxOtis [ToxOtis implementation with support for the aforementioned ontology]
Personal tools