SSWAP HTTP API


NAME

/makeRIG — make an RIG (Resource Invocation Graph)

SYNOPSIS

e.g., curl -d @<jsonFile> http://sswap.info/api/makeRIG[?prefix1=... [&prefix2=...]]

DESCRIPTION

/makeRIG is the basename of a URL for a RESTful web service that converts JSON (Javascript Object Notation) into a SSWAP OWL RDF/XML Resource Invocation Graph (RIG). Input is sent to the URL via a HTTP POST, for example by a program such as curl or wget. A HTTP GET on /makeRIG (for example, as initiated by visiting the URL with a browser) returns this manual page. Content negotiation may be used to return a machine parsable JSON schema if the requested response MIME type is application/json.

A Resource Invocation Graph (RIG) is a human-readable, machine-parsable description of the input data to a semantic web service using the SSWAP Protocol. The use of OWL allows an RIG to describe its input data and requested mapping to output data in terms that are amenable to a computable logic. An RIG for a given service is similar to the RDG (Resource Description Graph; see /makeRDG) for the service: it is essentially the RDG with the necessary input data added to the graph. RDGs are retrievable by a simple HTTP GET on a known service, or discoverable at http://sswap.info.  RIGs are OWL DL RDF/XML documents that follow the SSWAP Protocol and are used to invoke a service.

When services use the SSWAP Java API to handle their semantic services, the SSWAP machinery automatically translates between the vocabulary of the client RIG and the host RDG.  For example, consider a snippet from an RDG that defines a property and gives it a default value:

    "thisSite:accessionID" : 3

In this example, thisSite:accessionID would be resolvable to a URL; a HTTP GET on the URL would return the OWL RDF/XML definition for the property accessionID (N.B., browse the many ontologies and their properties at http://sswapmeet.sswap.info; users may host their own ontologies anywhere on the web).  The RDG uses this property in its service definition and states a default value of 3. Exercising one of the tenets of the semantic web--that Anyone can say Anything about Anything--someone else, somewhere else, uses /makeProperty to state that:

    "mySite:myAccessionID" : {

        "rdfs:subPropertyOf" : "thisSite:accessionID"

    }

and then creates an RIG with /makeRIG with the snippet:

    "mySite:myAccessionID" : 5

and sends it to the service.  Based on the formal semantics of rdfs:subPropertyOf, the service requirements are met (i.e., by logical implication thisSite:accessionID has a value), even though this is not obvious because nowhere in the RIG is there an explicit mention of thisSite:accessionID. Upon invocation with mySite:myAccessionID, the SSWAP semantic machinery will dereference mySite:myAccessionID and determine that thisSite:accessionID = 5 must be true based on the semantics of rdfs:subPropertyOf. This reasoning is done at transaction time. This interception and translation occurs on the server servicing the service's invocation. The result is that the service "sees" its own vocabulary (thisSite:accessionID) and the correct invocation value (5).  The service's business logic need not concern itself with this translation.  The service then constructs a response--the "action" of the service based on its input--and packages it into an RRG (Resource Response Graph; see /makeRRG) for return to the client. When the client parses the RRG, it will see it's old mySite:myAccessionID = 5 and need not concern itself with the host's translation. The client "knows" how to parse the RRG, because being a SSWAP graph compliant with the protocol, it is almost identical to the client's own RIG, expect now with the service's response data added to the RRG's sswap:Object (See the SSWAP Protocol).

RIGs use RDGs to enable automated semantic matching, as possible, between service invocation vocabularies and semantics (as used by a client) and service description vocabularies and semantics as used by the service. RIGs should be logically consistent with the statements of the RDG: the sswap:Resource of the RIG must be a subclass of the sswap:Resource of the RDG; its sswap:Subject must be a superclass of the RDG's sswap:Subject; its sswap:Object must be a subclass of the RDG's sswap:Object.  RIGs that do not follow this logical test may be rejected by the service; default behavior is to return the RIG as an RRG (Resource Response Graph; see /makeRRG) without modification.

/makeRIG creates RDF/XML RIGs from a simplified JSON input specification and the RDG at the <ResourceURI> (see below). RIGs tend to be ephemeral; they are not web resources, but are created on-the-fly, used, and consumed. Yet, as RDF/XML documents, they could be hosted on the web like any other document, for example to create a repository of invocation graphs.

/makeRIG is hosted as a public service at http://sswap.info/api/makeRIG.

Self-invocation

Services can be invoked directly from HTTP GET query strings with no POSTed RIG.  In this manner, the SSWAP servlet parses the query string to construct an RIG from its own RDG and self-invokes.  This functionality is performed by AbstractSSWAPServlet in the Java API (see SEE ALSO).  In query string parsing, terms without a prefix (e.g., ?myProperty=myValue) are matched against the default namespace of the RDG, if any.  Use the empty string "" prefix to define the default namespace in the RDG (see JSONSyntax and /makeRDG). Terms with a prefix (e.g., ?somePrefix:myProperty=myValue) are matched against prefixes defined in the RDG. Prefixes must either match those as exactly defined in the RDG, or be defined in the query string by appending a colon (:) after a prefix and before the URI assignment (e.g., ?myNewPrefix:=http://.../). Query string prefix assignment may occur anywhere in the query string, but only one prefix assignment per URI is retained. It is illegal to attempt to re-assign a prefix already assigned in the RDG. Prefixes are optional; properties may be used as fully qualified URIs with value assignments (e.g., ?http://.../myTerm=5). Terms that do not match any prefix are converted into URIs by prepending the term with urn:. These terms are passed on to the RIG generation process, but if they fail to match a fully qualified RDG term they will be ignored. Any term without a value assignment is silently dropped (e.g., ?myProperty). Multiple items may be placed in the query string using an ampersand (&) (e.g., ?myProperty=myValue&somePrefix:someProperty=someValue). Auto-generated RIGs are subject to the semantic translation described above, thus in the above example both of the following query strings are valid:

    ?thisSite:accessionID=3

  ?mySite:myAccessionID=5&mySite:=http://.../

Note the defining statement for the prefix mySite; without which mySite is likely undefined in the RDG and myAccessionID would be unresolved and therefore ignored. Name spaces (e.g., http://.../) should almost always end in a slash (/) or a hash (#), depending on the requisites for a fully qualified term in the name space ontology. In the example above, the prefix could be replaced with a fully qualified property to yield:

    ?http://.../myAccessionID=5

Properties are dereferenced, as possible, for rdfs:range restrictions. Thus, for example, if properties p:a, p:b, and p:c are each defined with an rdfs:range of xsd:string, xsd:boolean, and xsd:integer respectively, then the following:

   ?p:a=1&p:b=1&p:c=1

would attempt to assign the values "1", 1 (== true), and 1 to each respectively. Incorrect datatype assignments will render the RIG logically inconsistent and preclude invocation.

By default, property assignments are performed on all subjects generated by the RDG.  One may restrict a property to the resource itself by appending the tilde (~) to the property name, e.g.:

    ?login~=mickey&token~=m0us3y&thisSite:accessionID=3

The above will resolve the terms login and token against the default RDG namespace and apply the properties and their values respectively to the sswap:Resource; it will resolve accessionID against the thisSite namespace as defined in the RDG and apply it with the value 5 to every sswap:Subject. Properties to be assigned to the resource must end with a tilde (~) prior to the assignment operator (=) to be recognized as such. The tilde (~) is not part of the property name and is stripped before the property's use in the auto-generated RIG.

See USAGE NOTES on self-invocation support.

Quick Start

Here, we use the program curl to POST the in-line JSON content to the public /makeRIG service:

curl -d '

{

  "prefix" : {

    "iplant"         : "http://sswap.info/iplant/",

    "taxonomyLookup" : "http://sswapmeet.sswap.info/taxonomyLookup/",

    ""               : "http://sswapmeet.sswap.info/NCBITaxonomyRecord/"

  },


  "iplant:svc/taxonomyLookup" : { },


  "mapping" : { "_:subject" : ":TaxonomyRecord" },


  "definitions" : {

    "_:subject" : {

        "rdf:type"     : "taxonomyLookup:request/TaxonomyLookupRequest",

        ":commonName" : "barrel medic"

        }

    }

}

' http://sswap.info/api/makeRIG

(For Windows CMD.exe users, see USAGE NOTES below). Note that the RIG follows the RDG for iplant:svc/taxonomyLookup (the <ResourceURI>) but does not reiterate what is already defined for the service at its URL. The RIG specifies the input value (e.g., "barrel medic"). The response from /makeRIG is a SSWAP OWL RDF/XML RIG suitable for POSTing to the service for invocation. The service can also make its own RIG (thereby bypassing the need for the user to use this API end-point to make a RDF/XML RIG) and self-invoke upon GET query string invocation, e.g.:

    http://sswap.info/iplant/svc/taxonomyLookup?commonName=barrel+medic

(the space character in "barrel medic" is replaced with a '+' per URL encoding standards). Developers implementing a service can use the Software Development Kit to aid in handling the invocation and response of the service.

JSON Format

Input follows standard JSON syntax with built-in support for generating SSWAP documents as described in the JSON Syntax (see also SSWAP HTTP API).  RIGs follow the guidelines of RDGs (see /makeRDG) with the addition that RIGs include data values for invocation.

EXAMPLES

The command:

curl http://sswap.info/api/makeRIG

executes an HTTP GET and retrieves this manual page. Because this is a simple GET, you can accomplish the same action by simply visiting the link with your browser. Alternatively, to have a machine-readable schema returned instead of HTML, use content negotiation to request the JSON schema:

curl -H 'Accept: application/json' http://sswap.info/api/makeRIG

To generate an RIG from JSON, the command:

curl -d @myJSONInputFile http://sswap.info/api/makeRIG

will POST the contents of myJSONInputFile to the public service.  The response is a SSWAP OWL RDF/XML RIG. Optionally, you can inform the service of the MIME type of the content you are sending by adding the header option -H 'Content-Type: application/json'.  The service is guaranteed to accept this MIME type, so for generating content programmatically, this header option guarantees that the input will be accepted.

On many operating systems you can also in-line content such as in the Quick Start example above and the example below:

curl -d '

{

  "api" :  "/makeRIG",


  "prefix" : {

    "iplant" : "http://sswap.info/iplant/",

    "tnrs"   : "http://sswapmeet.sswap.info/tnrs/",

    ""       : "http://sswapmeet.sswap.info/tnrs/request/"

  },


  "iplant:svc/tnrs" : {

    "tnrs:retrieve" : "best"

   },


  "mapping" : { "_:subject" : "tnrs:Item" },


  "definitions" : {

    "_:subject" : {

        "rdf:type" : ":TNRSRequest",

        ":names" : "zea"

    }

   }

}

' http://sswap.info/api


Note the similarity between the RIG and the service's actual JSON RDG at http://sswap.info/iplant/svc/tnrs.json. The RIG simply adds the service's parameter ("tnrs:retrieve" : "best") and input data (":names" : "zea"). Details of the service's RDG definition do not and should not be replicated.

USAGE NOTES

The Windows CMD.exe command shell does not recognize in-line quoted strings as in the examples above; in that case, save the contents into a file and use the -d @myJSONInputFile syntax.

/makeRIG is a convenience service to enable a non-semantic JSON specification to generate a semantic SSWAP OWL RDF/XML RIG. Using it guarantees that the resultant RIG is OWL DL and SSWAP compliant, while allowing the specification to be in JSON instead of the more obtuse OWL RDF/XML. Yet ultimately it is the RDF/XML RIG that is used by the semantic web service.  It is perfectly acceptable to take an existing RDG (simply do a HTTP GET on the service) and edit the RDF/XML directly to create an RIG.  If creating RIG's without the aid of /makeRIG, authors should validate the graph at http://sswap.info. Currently, graph validation is not specific to RIGs, so if not using /makeRIG, only generic OWL validation is available. Developers are encouraged to use the SSWAP Java API for finer-grained control than is available with the HTTP API.

Self-invocation is supported by services using the SSWAP Java API.

DIAGNOSTICS

If /makeRIG returns content (RDF/XML), it is guaranteed to be a valid SSWAP OWL DL RIG. In these cases the HTTP response code is always '200 OK'. If /makeRIG cannot return content (for example, because of an unrecoverable parsing error on the JSON input or the lack of a dereferenceable RDG), it will return a HTTP error code other than '200 OK'. /makeRIG requires an existing and valid RDG to be available from the <ResourceURI> at the time it is run; if dereferencing this URL fails to return a valid RDG, /makeRIG will fail.


Note: curl may return an exit code of 0 (success) even if the HTTP response code is not 200. See curl for details and ways to change this behavior.

STANDARDS

Input format is standard JSON, with recognition for the reserved strings "prefix", "imports", "mapping", and "definitions". Output format is OWL 2 (DL) RDF/XML.

SEE ALSO

SSWAP Home: sswap.info

SSWAP Wiki: sswap.info/wiki

SSWAP Just-In-Time Ontology Editor: sswap.info/jit

SSWAP Java API: sswap.info/javadocs

SSWAP SDK (Software Development Kit): sswap.info/sdk

JSON: http://json.org

JSON validators: http://www.jslint.com, http://www.jsonlint.com

OWL: http://www.w3.org/TR/owl2-overivew

RDF/XML: http://www.w3.org/TR/REC-rdf-syntax

AUTHORS

Damian Gessler, Blazej Bulka

AVAILABILITY

The software is open source.

/makeRIG