SSWAP HTTP API


NAME

/makeRRG — make an RRG (Resource Response Graph)

SYNOPSIS

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

DESCRIPTION

/makeRRG is the basename of a URL for a RESTful web service that converts JSON (Javascript Object Notation) into a SSWAP OWL RDF/XML Resource Response Graph (RRG). Input is sent to the URL via a HTTP POST, for example by a program such as curl or wget. A HTTP GET on /makeRRG (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 Response Graph (RRG) is a human-readable, machine-parsable description of the output data (the result) of a semantic web service using the SSWAP Protocol. The use of OWL allows an RRG to describe its mapping of input data to output data in terms that are amenable to a computable logic. An RRG for a given service is similar to its invoking RIG (Resource Invocation Graph; see /makeRIG. RIGs are OWL DL RDF/XML documents that follow the SSWAP Protocol and are used to invoke a service).  RRGs are essentially RIGs with the necessary output data added to the graph.

Services that use the Software Development Kit and the SSWAP Java API do not need to use this service: an RRG is created as a response to service execution. For Web sites that use Web Discovery this is the service that translates their JSON data. Such Web sites do not need to call this service directly; it will be performed as part of Web Discovery.

Best practices on RRG generation follow the guidelines of "Do no harm," "Ignore what you don't understand," and maintain logical implication. When a service receives an RIG on invocation it will generate and return a RRG as the response.  The client sending the RIG may or may not have reasoning services available, so a service should preserve the RIG syntactical structure as much as possible and ignore statements it does not understand. An RRG should be logically consistent with both the RIG and the service's own RDG, such that a RRG is always a valid RIG to the same service, even though if passed back to the service no further modifications may be possible.

/makeRRG creates RDF/XML RRGs from a simplified JSON input specification and the RDG at the <ResourceURI> (see below). RRGs may be ephemeral; they are not web resources, but are created on-the-fly in response to service invocation. Yet because RRGs document the sswap:Subject to sswap:Object mapping, they also stand as persistent statements of how ontologically tagged data has been mapped by the service.  RRGs may be used to start new pipelines at sswap.info.

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

Quick Start

Here, we use the program curl to POST the in-line JSON content to the public /makeRRG 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" : "http://purl.org/taxa/ncbi/3880" },


  "definitions" : {


    "_:subject" : {

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

        ":commonName" : "barrel medic"

    },


    "http://purl.org/taxa/ncbi/3880" : {

        "rdf:type"        : ":TaxonomyRecord",

        ":commonName"     : "barrel medic",

        ":scientificName" : "Medicago truncatula",

        ":taxonomyID"     : "3380",

        ":recordURL"      : "http://purl.org/taxa/ncbi/3880"

        }

    }

}

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

(For Windows CMD.exe users, see USAGE NOTES below). The <ResourceURI> is iplant:svc/taxonomyLookup. Note that the RRG maps the input (_:subject) based on its properties (:commonName" : "barrel medic) to a resource on the Web (http://purl.org/taxa/ncbi/3880) and then marks up that Web resource by typing it as :TaxonomyRecord and adding its properties. Using URLs as graph nodes in both input and output statements is a way to pass references to data without embedding the data itself as RDF/XML.

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). RRGs follow the guidelines of RDGs (see /makeRDG) with the addition that RRGs include data values from invocation and for response.

EXAMPLES

The command:

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

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

To generate an RRG from JSON, the command:

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

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


  "prefix" : {

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

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

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

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

  },


  "iplant:svc/tnrs" : {

    "tnrs:retrieve" : "best"

   },


  "mapping" : { "_:subject" : "http://www.tropicos.org/Name/40028236" },


  "definitions" : {


    "_:subject" : {

        "rdf:type" : ":TNRSRequest",

        ":names" : "zea"

    },


    "http://www.tropicos.org/Name/40028236" : {

        "rdf:type" : [ "tnrs:Item", "mime:text/Html" ],

        "tnrs:selected" : "true",

        "tnrs:matchedFamilyScore" : "",

        "tnrs:acceptedNameUrl" : "http://www.tropicos.org/Name/40028236",

        "tnrs:infraspecific1Epithet" : "",

        "tnrs:epithetScore" : "",

        "tnrs:speciesMatchedScore" : "",

        "tnrs:authorAttributed" : "L.",

        "tnrs:acceptedName" : "Zea",

        "tnrs:author" : "",

        "tnrs:url" : "http://www.tropicos.org/Name/40028236",

        "tnrs:infraspecific1Rank" : "",

        "tnrs:overall" : "1",

        "tnrs:speciesMatched" : "",

        "tnrs:genus" : "Zea",

        "tnrs:familySubmitted" : "",

        "tnrs:infraspecific2EpithetScore" : "",

        "tnrs:unmatched" : "",

        "tnrs:genusScore" : "1",

        "tnrs:nameScientific" : "Zea",

        "tnrs:infraspecific1EpithetScore" : "",

        "tnrs:acceptance" : "No opinion",

        "tnrs:scientificScore" : "1",

        "tnrs:nameSubmitted" : "zea",

        "tnrs:acceptedAuthor" : "L.",

        "tnrs:epithet" : "",

        "tnrs:group" : "0",

        "tnrs:infraspecific2Rank" : "",

        "tnrs:infraspecific2Epithet" : "",

        "tnrs:family" : "Poaceae",

        "tnrs:annotation" : "",

        "tnrs:matchedFamily" : "",

        "tnrs:authorScore" : ""

    }

   }

}

' http://sswap.info/api


Note that the RRG retains the original input data from the RIG: both the service's parameter assignment ("tnrs:retrieve" : "best") and the input data ("_:subject" : { "rdf:type" : ":TNRSRequest", ":names" : "zea" }). By retaining the mapping information, an RRG is a persistent set of logical statements of a data-driven mapping problem. 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 embedded definitions within the text of an RRG, a stronger model is to place those definitions at web-accessible URIs, such as is done with :TNRSRequest and tnrs:Item/makeRRG will deference these URIs as part of determining constraints and constructing the graph.

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.


/makeRRG is a convenience service to enable a non-semantic JSON specification to generate a semantic SSWAP OWL RDF/XML RRG. Using it guarantees that the resultant RRG is OWL DL and SSWAP compliant, while allowing the specification to be in JSON instead of the more obtuse OWL RDF/XML. Yet if the developer must map the invoking RIG to the response RRG outside of the SSWAP framework, which can be error-prone. Developers are encouraged to use the SSWAP Java API for finer-grained control than is available with the HTTP API.

DIAGNOSTICS

If /makeRRG returns content (RDF/XML), it is guaranteed to be a valid SSWAP OWL DL RRG. In these cases the HTTP response code is always '200 OK'. If /makeRRG cannot return content (for example, because of an unrecoverable parsing error on the JSON input or because the RRG is not logically implied by the RDG), it will return a HTTP error code other than '200 OK'. /makeRRG 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, /makeRRG 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.

/makeRRG