SSWAP HTTP API


NAME

/makePDG — make a PDG (Provider Description Graph)

/makeRDG — make a RDG (Resource Description Graph)

/makeRIG — make a RIG (Resource Invocation Graph)

/makeRRG — make a RRG (Resource Response Graph)

/makeRQG — make a RQG (Resource Query Graph)

/makeType — make a type (OWL Class)

/makeProperty — make a property (OWL ObjectProperty or OWL DatatypeProperty)

SYNOPSIS

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

DESCRIPTION

The SSWAP HTTP API is a set of URLs for RESTful web services that convert JSON (Javascript Object Notation) into SSWAP OWL RDF/XML graphs. Input is sent to a URL via a HTTP POST, for example by a program such as curl or wget. A HTTP GET on a URL (for example, as initiated by visiting the URL with a browser) returns its manual page. Content negotiation may be used to return a machine parsable JSON schema if the requested response MIME type is application/json.

On an HTTP POST, if the API endpoint is not specified (e.g., http://sswap.info/api instead of http://sswap.info/api/makeRDG), then the endpoint is determined by the JSON "api" directive in the submitted text. If the API URL has an optional prefix substitution query string (e.g., ?aPrefix=http://localhost:8080/dev/&aPrefix2=http://localhost:8080/dev2/), then the substitution will be used. These features aid development by allowing simple scripts to process files for multiple endpoints in production and development (testing) settings.  For more information, see the JSON Syntax page.

SSWAP (Simple Semantic Web Architecture and Protocol) is an architecture and protocol for semantic web services. SSWAP uses the W3C standard of OWL to ground a web services model on a computable semantics and logic (specifically, a first-order description logic when the underlying semantics confirms to OWL DL). SSWAP achieves this by formulating an architecture and a protocol. The HTTP API allows developers to generate SSWAP RDF/XML graphs using JSON. In this manner, the HTTP API addresses an impedance mismatch between an easy to use, non-semantic JSON snippet and a semantic, SSWAP-compliant document.

Providers of services host a Provider Description Graph (see /makePDG); each service describes itself with a Resource Description Graph (see /makeRDG); services are invoked with a Resource Invocation Graph (see /makeRIG), and responses are returned in a Resource Response Graph (see /makeRRG).  Resources (services) can be semantically discovered by sending a Discovery Server (see http://sswap.info/developer.jsp) a Resource Query Graph (see /makeRQG).

The graphs--RDF/XML documents--all follow the SSWAP protocol. Their structure is consistent and similar, thus a typical workflow is from RDG to RQG to RIG to RRG, all amenable to the same syntax and underlying processing code base. A quick translation can convert an RRG into an RQG or RIG, and the process can continue across the web.

SSWAP graphs allow the description of third-party idiosyncratic data and services using the OWL semantics of classes (called "types"; see /makeType) and properties (see /makeProperty). Data and service integration is enabled by allowing anyone to introduce new classes or properties--but importantly, such extension is always within the sandbox of an RDF/XML syntax and OWL semantics, thus extension is amenable to high throughput, computational handling.  SSWAP treats each ontological term as an independently dereferenceable URL, and thus encourages a marketplace of terms loosely grouped as ontologies to establish a community-driven, organic development of shared, domain-specific semantics.

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). JSON is sensitive to a strict syntax.  See SEE ALSO for JSON validators.

USAGE NOTES

The HTTP API are convenience services to enable a non-semantic JSON specification to generate a semantic SSWAP OWL RDF/XML graph. Using them guarantees that a resultant graph is OWL DL and SSWAP compliant, while allowing the specification to be in JSON instead of the more obtuse OWL RDF/XML. Syntactical compliance cannot by itself enforce an architectural behavior. Developers are encouraged to consult and use the SSWAP Java API for finer-grained control, and to extend the AbstractSSWAPServlet class to achieve compliant behavior.

DIAGNOSTICS

If an HTTP API call returns content (RDF/XML), it is guaranteed to be a valid SSWAP OWL DL graph. In these cases the HTTP response code is always '200 OK'. If a call 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'.


The HTTP API is fault-tolerant, meaning that JSON constructs that cannot be resolved into OWL DL statements are ignored.  The API tries to always return a graph (OWL DL), if possible, and will silently ignore input statements that fail validation criteria yet otherwise allow a DL graph to be returned. JSON parsing errors are not ignored and an error message is returned.

STANDARDS

Input format is standard JSON, with recognition for reserved strings. Output format is OWL 2 (DL) RDF/XML.

SEE ALSO

SSWAP Home: sswap.info

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-overview

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


Gessler DDG, Schiltz GS, May GD, Avraham S, Town CD, Grant D, Nelson RT SSWAP: A Simple Semantic Web Architecture and Protocol for semantic web services. BMC Bioinformatics 2009, 10:309 doi:10.1186/1471-2105-10-309.

AUTHORS

Damian Gessler, Blazej Bulka

AVAILABILITY

The software is open source.