SSWAP HTTP API


NAME

/makeRDG — make an RDG (Resource Description Graph)

SYNOPSIS

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

DESCRIPTION

/makeRDG is the basename of a URL for a RESTful web service that converts JSON (Javascript Object Notation) into a SSWAP OWL RDF/XML Resource Description Graph (RDG). Input is sent to the URL via a HTTP POST, for example by a program such as curl or wget. A HTTP GET on /makeRDG (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 Description Graph (RDG) is a human-readable, machine-parsable description of a semantic web service using the SSWAP Protocol. The use of OWL allows an RDG to describe a service in terms that are amenable to a computable logic. The RDG is hosted at the URL of the service such that a HTTP GET on the service URL (with no query string parameters) returns the RDG, while an HTTP POST (with an RIG [Resource Invocation Graph] as the body of the POST; see /makeRIG) or an HTTP GET with a query string invokes the service.  RDGs are OWL DL RDF/XML documents that follow the SSWAP Protocol and are used to describe a service.

RDGs allow 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.  They set the template for the service's invocation (via a Resource Invocation Graph; see /makeRIG), its return data (as a Resource Response Graph; see /makeRRG) and semantic discovery via query graphs (a Resource Query Graph; see /makeRQG).

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

Examples of RDGs are numerous: search on anything at sswap.info; on the results' page click on a service's Service URI to view its RDF/XML RDG. View the canonical RDG at sswap.info/examples/resources/canonical/canonicalResource.

Quick Start

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

curl -d '

{

  "prefix" : {

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

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

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

  },


  "iplant:svc/taxonomyLookup" : {


    "sswap:name"               : "Taxonomy Lookup Service",

    "sswap:oneLineDescription" : "A service that accepts a common organism name, such as 'dog' or 'mouse' and returns an NCBI taxonomic record for that taxon.",

    "sswap:icon"               : "iplant:icons/iPlant.png",

    "sswap:metadata"           : "taxonomyLookup:metadata.txt",

    "sswap:providedBy"         : "iplant:iPlantCollaborative"

   },


  "mapping" : {

    "taxonomyLookup:request/TaxonomyLookupRequest" : ":TaxonomyRecord"

  }

}

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

(For Windows CMD.exe users, see USAGE NOTES below). The example shows numerous features of the JSON syntax, including default namespace designation and QName support (e.g., ":TaxonomyRecord" as an abbreviation for http://sswapmeet.sswap.info/NCBITaxonomyRecord/TaxonomyRecord), use of SSWAP predicates (e.g., sswap:name; rdf:, rdfs:, xsd:, and owl: namespaces are also available), user-defined classes and predicates, and a mix-n-match with other ontology terms on an on-demand, per term basis.

The response from /makeRDG is a SSWAP OWL RDF/XML RDG suitable for semantic web services. The resultant RDG should be hosted on the web at the URL used in the RDG's construction (myResources:taxonomyLookupService/taxonomyLookupService). Once a service is defined, developers 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).


Main components of the JSON input are:

1.  An opening curly brace ({) signifying the start of a JSON object;

2.  An optional "api" : "/makeRDG" , string:string construct that specifies the API end-point. Used only if the JSON is POSTed to the root end-point http://sswap.info/api, whereby it is used to direct the input to the /makeRDG end-point.

3.  An optional "prefix" : { ... } string:object construct to enable a QName-like capability for writing abbreviated URIs; e.g.:

  "prefix" : {

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

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

        },

Note the use of the empty string ("") prefix to establish a default namespace for the document. See JSONSyntax for details.

4.  An optional "imports" : [ ... ] string:array construct to enable an owl:imports-like capability for importing zero, one, or more OWL files during the PDG generation; e.g.:

    "imports" : [

            "myPrefix:myOWLImportsFile",

            more as and if necessary (comma-separated)

        ],

SSWAP performs automatic URL dereferencing and caching for retrieving term definitions; an "imports" directive is rarely needed and not should not be used unless required.

5.  A required "<ResourceURI>" : { ... } string:object construct that defines the service according to the SSWAP Protocol for a sswap:Resource<ResourceURI> is the URL of the service, and consequently the URL where the RDG is to be hosted. For service properties, only two properties are required: a name, and a link to who is providing the resource; e.g.:

    "sswap:name" : "My Service name",

    "sswap:providedBy" : "myPrefix:myProvider"

/makeRDG will automatically construct other aspects of the protocol.  The value of the property sswap:providedBy should resolve to a valid PDG (Provider Description Graph) as created by /makePDG. If an RDG claims ownership by a provider that is not a super-path of itself (i.e., the URL specified by the sswap:providedBy property is not parent of the <ResourceURI>), then the PDG must reciprocate the claim with a sswap:providesResource statement to the RDG. Validation of sswap:providesResource and sswap:providedBy claims is done at service publication time, not at PDG or RDG creation time. Other properties enhance service capabilities (such as other sswap:Resource properties or setting default values for user-properties) are encouraged but not required.  See sswap:Resource and the example below;

6.  A required "mapping" : { ... } string:object  or "mapping" : [ ... ] object construct that specifies how the service maps its input to its output.  A powerful construct is a simple 1:1 mapping of a sswap:Subject to a sswap:Object. Even though this is a 1:1 mapping, both the subject and object may be of multiple types (see /makeType) and have multiple properties including the embedding of subgraphs (see /makeProperty).  More complicated mappings in the forms of one:many (1:*), many:one (*:1), many:many (*:*), and many:<*:*> mappings are supported; viz.:

  1. 1:1        "mapping" : { "_:subject" : "_:object" }

  2. 1:*   "mapping" : { "_:subject" : [ "_:object1, "_:object2" ] }

  3. *:1    "mapping" : {

               "_:subject1" : "_:object",

               "_:subject2" : "_:object"

           }

  1. *:*    "mapping" : {

                "_:subject1" : [ "_:object1, "_:object2" ],

                "_:subject2" : [ "_:object2, "_:object3" ]  

            }

  1. *:<*:*> "mapping" : [

                { as above... },

                { as above... }

            ]

    The last case expresses an array of mappings, such that the service will satisfy any or all of the 1:1, 1:*, *:1, or *:* alternatives. In the snippets above the namespace is the reserved prefix "_:", used to specify placeholder "blank nodes" as is common in RDF. These may then be referenced by name in the definitions directive.

    By placing cardinality constraints on properties used to define types in the mapping directive, services may distinguish and communicate differences between optional properties (the service will accept 0 or more) and required properties (minimum number of 1).  See JSON Syntax.

7.  An optional "definitions" : { ... } string:object construct for defining attributes on the placeholder subjects and objects from the mapping directive. In this construct one may also set data default values by assigning values to properties, as in the Quick Start example.

8.  A closing curly brace (}) signifying the end of the JSON object.

JSON is sensitive to a strict syntax.  See SEE ALSO for JSON validators.

EXAMPLES

The command:

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

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

To generate an RDG from JSON, the command:

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

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


  "prefix" : {

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

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

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

  },


  "iplant:svc/tnrs" : {


    "sswap:name"               : "Taxonomic Name Resolution Service",

    "sswap:oneLineDescription" : "A free utility for correcting and standardizing plant names",

    "sswap:aboutURI"           : "http://tnrs.iplantcollaborative.org",

    "sswap:icon"               : "iplant:icons/tnrs.png",

    "sswap:providedBy"         : "iplant:iPlantCollaborative",


    "tnrs:retrieve"            : "best"

   },


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


"definitions" : {

    "_:subject" : {

        "rdf:type" : ":TNRSRequest",

        ":names" : "zea"

    },

    "_:object"  : {

        "rdf:type" : "tnrs:Item"

    }

   }

}

' http://sswap.info/api

The contents between and including the opening and closing curly braces { } are exemplary of the contents of myJSONInputFile. When in-lining content, note the use of opening and closing single quotes (') around the braces { }; this protects the contents from interpretation by the shell in many operating systems. The mapping of subject to object, and their subsequent typing in the definitions section follows the protocol at http://sswap.info/protocol.  SSWAP uses a highly distributed model of data re-use, thus while it is possible to embed definitions within the text of an RDG, a stronger model is to place those definitions at web-accessible URIs, such as is done with tnrs:retrieve and :TNRSRequest/makeRDG will deference these URIs as part of determining constraints and constructing the graph.

The assignment of the default namespace ("") to the TNRS ontology root directory means that the service's GET query string invocation, viz:

    http://sswap.info/iplant/svc/tnrs?http://sswapmeet.sswap.info/tnrs/request/names=zea

becomes simply:

    http://sswap.info/iplant/svc/tnrs?names=zea

or as a two parameter, multiple prefix example:

    http://sswap.info/iplant/svc/tnrs?names=zea&tnrs:retrieve=best

It is recommended that a default namespace is always defined so as to enable this short-hand on the "primary" parameter or data ontology prefix. For more on GET query string self-invocation see /makeRIG.

Note also the assignment of default values both as service parameters ("tnrs:retrieve" : "best") and input data (":names" : "zea"). Default values are automatically added to RIGs on invocation (for GET query string invocation, use "?-". Default values are shown here as an example only; the on-line version of this service does not use default assignments, so execution without data will not proceed).

If a definitions directive sets a single rdf:type for the Subject or Object, and the type definition is hosted on the web and available when the API is called to create the RDG, then the directive may be skipped by simply stating the types in the mapping, e.g.:


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

The above will be interpreted as mapping of data of type :TNRSRequest to data of type tnrs:Item.

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.


/makeRDG is a convenience service to enable a non-semantic JSON specification to generate a semantic SSWAP OWL RDF/XML RDG. Using it guarantees that the resultant RDG 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 RDG 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 define a new service.  If creating RDG's without the aid of /makeRDG, authors should validate the RDG at http://sswap.info. Developers are encouraged to use the SSWAP Java API for finer-grained control than is available with the HTTP API.

DIAGNOSTICS

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

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

AUTHORS

Damian Gessler, Blazej Bulka

AVAILABILITY

The software is open source.

/makeRDG