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.

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-orderdescription 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.