SSWAP HTTP API


NAME

/makeRQG — make an RQG (Resource Query Graph)

SYNOPSIS

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

DESCRIPTION

/makeRQG is the basename of a URL for a RESTful web service that converts JSON (Javascript Object Notation) into a SSWAP OWL RDF/XML Resource Query Graph (RQG). Input is sent to the URL via a HTTP POST, for example by a program such as curl or wget. A HTTP GET on /makeRQG (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 Query Graph (RQG) is a human-readable, machine-parsable description of a query for semantic web services using the SSWAP Protocol. The use of OWL allows an RQG to describe its query in terms that are amenable to a computable logic. A query is a request for discovery: find all services that match the query. An RQG is similar to an RDG (Resource Description Graph; see /makeRDG. RDGs are OWL DL RDF/XML documents that follow the SSWAP Protocol and are used to describe services).  RQGs are essentially RDGs with a (possibly empty string) regex as the URI of the sswap:Resource.  (See the SSWAP Protocol).

RQGs are POSTed to a Discovery Server, such as at http://sswap.info/discover.  The response is a list of services that match the following constraints:

  1. Each service's sswapResource is a subtype of the RQG's sswapResource, and

  2. Each service's sswapSubject is a super-type of the RQG's sswapSubject, and

  3. Each service's sswapObject is a subtype of the RQG's sswapObject, and

  4. Each service's sswapResource URI is a regex match to the RQG's sswapResource URI.

The token sswapResource refers to the RDF subject that is of rdf:type sswap:Resource as defined in each service's RDG or in the RQG.  Similarly, sswapSubject and sswapObject refer to their sswap:Subject and sswap:Object counterparts respectively. An RQG's sswapResource must be either an anonymous node (no URI, which is interpreted to match any service), or it must be a SPARQL regular expression (see XQuery 1.0 and XPath 2.0 Functions and Operators).

The matching constraints ensure that the services returned are:

  1. As specific or more specific than the RQG service type request, and

  2. Accept data as general or more general than the RQG input data type, and

  3. Return data as specific or more specific than the RQG output data type, and

  4. Are filtered on a URI match, if any, for the service.

By definition, types (OWL classes) are always subtypes of themselves (a class is a subclass of itself). Thus, the default case of an RQG whose sswapResource has no URI and is not typed (see /makeType) would match all services (no filtering on service type). Similarly, an RQG whose sswapObject is not typed matches all services (services returning any type of data).  An RQG with a typed sswapSubject matches only those services that accept that type or a super-type.  In this manner, matched services are guaranteed to be able to operate on the query input data.  In the special case of a sswapSubject that is not typed, only services that accept owl:Thing with no further type restriction satisfy the superclass criteria. This is rarely what is useful; rather, common queries are to find all services that accept any input (for example, when used in conjunction with filtering on service type or output types). Thus an exception is implemented such that an untyped sswapSubject (i.e., belonging only to the type owl:Thing) matches any subject and thus is ignored as a query matching criteria. A type not equivalent to owl:Thing must be specified for at least one of sswapResource, sswapSubject, or sswapObject.

Services returned as final matches have RDGs that satisfy the intersection of all constraints. Typing is determined by a reasoner and may include "anonymous" (unnamed, implied types) as determined by examining the node's OWL constructs (e.g., owl:Restriction). RQGs contribute an important role in linking service and data descriptions with service and data discovery under semantic reasoning. Service and data types may be complex, named or anonymous types; subsumption determination is performed by a reasoner at transaction time.

/makeRQG creates RDF/XML RQGs from a simplified JSON input specification. As a convenience, sswap.info/query may accept RDGs or other graphs in place of RQGs. In such cases, the graph is internally converted into an RQG by replacing the sswapResource with an anonymous node of the same type(s).

RQGs tend to be ephemeral; they are not web resources, but are created on-the-fly for the purpose of service discovery. Yet, as RDF/XML documents, they could be hosted on the web like any other document, for example to create a repository of queries.

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

Quick Start

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

curl -d '

{

    "prefix" : { "taxa" : "http://sswapmeet.sswap.info/taxa/" },


    "" : { },


    "mapping" : { "" : "taxa:Taxa" }

}

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

(For Windows CMD.exe users, see USAGE NOTES below). The <ResourceURI> is empty (""), designating no filtering on the URI of putative matches. We leave the sswapSubject also untyped ("")  to mean "match any subject", and use a shorthand of URI types for the sswapObject.  The resultant RDF/XML RQG can be POSTed directly to sswap.info/query. Developers using queries in Java can use the Software Development Kit to aid in constructing RQGs.

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). RQGs follow the guidelines of RDGs (see /makeRDG) with the addition that RQGs support regex expressions as the URI of the sswapResource.

EXAMPLES

The command:

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

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/makeRQG

To generate an RRG from JSON, the command:

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

will POST the contents of myJSONInputFile to the public service.  The response is a SSWAP OWL RDF/XML RQG. 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" :  "/makeRQG",


  "prefix" : {

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

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

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

  },


  ".*tnrs.*" : {

    "sswap:providedBy" : "iplant:iPlantCollaborative"

   },


  "mapping" : { "" : "tnrs:Item" }


}

' http://sswap.info/api


This finds all services that have "tnrs" in their URL, filtered on being provided by  iplant:iPlantCollaborative, and that map any data to a tnrs:Item. Note that a type restriction must be given for at least one of sswapResource, sswapSubject, or sswapObject. The result from /makeRQG is a RDF/XML RQG ready for POSTing to sswap.info/query. The result of that is a JSON array of matching services: ["http://sswap.info/iplant/svc/tnrs"].

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.


/makeRQG is a convenience service to enable a non-semantic JSON specification to generate a semantic SSWAP OWL RDF/XML RQG. Using it guarantees that the resultant RQG is OWL DL and SSWAP compliant, while allowing the specification to be in JSON instead of the more obtuse OWL RDF/XML.

DIAGNOSTICS

If /makeRQG returns content (RDF/XML), it is guaranteed to be a valid SSWAP OWL DL RQG. In these cases the HTTP response code is always '200 OK'. If /makeRQG cannot return content (for example, because of an unrecoverable parsing error on the JSON input), it will return a HTTP error code other than '200 OK'.


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.

/makeRQG