SSWAP HTTP API


NAME

/makePDG — make a PDG (Provider Description Graph)

SYNOPSIS

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

DESCRIPTION

/makePDG is the basename of a URL for a RESTful web service that converts JSON (Javascript Object Notation) into a SSWAP OWL RDF/XML Provider Description Graph (PDG). Input is sent to the URL via a HTTP POST, for example by a program such as curl or wget. A HTTP GET on /makePDG (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 Provider Description Graph (PDG) is a human-readable, machine-parsable description of a provider of one or more semantic web services using the SSWAP Protocol. Example of service providers are  web sites, individuals, institutions, and so forth. The use of OWL allows a PDG to describe a provider in terms that are amenable to a computable logic. The PDG is hosted at the URL of the sswap:Provider node of the PDG such that a HTTP GET returns the PDG. HTTP GETs with query strings and HTTP POSTs are not defined for PDGs.  PDGs are OWL DL RDF/XML documents that follow the SSWAP Protocol and are used to describe a provider and its offered services. Because they do not describe services themselves, PDGs are simpler than RDGs (Resource Description Graphs; see /makeRDG).

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

Examples of PDGs 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. The PDG is indicated by the sswap:providedBy property. View an exemplar PDG at sswap.info/examples/resourceProvider.

Quick Start

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

curl -d '

{

  "prefix" : {

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

  },


  "iplant:iPlantCollaborative" : {

    "sswap:name" : "The iPlant Collaborative",

    "sswap:oneLineDescription" : "iPlant provider of SSWAP semantic web services"

  }

}

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

(For Windows CMD.exe users, see USAGE NOTES below). In general, the API accepts QName-like constructs (e.g., "iplant:iPlantCollaborative") interchangeably with their fully qualified URIs (e.g., "http://sswap.info/iplant/iPlantCollaborative").  The sswap prefix, as well as the prefixes rdf, rdfs, xsd, and owl are always available and do not need to be defined explicitly.

The response from /makePDG is a SSWAP OWL RDF/XML PDG suitable for semantic web services. The resultant PDG should be hosted on the web at the <ResourceURI> (e.g., at iplant:iPlantCollaborative). Subsequently defined services will each, in their separate RDGs,  reference the common PDG via sswap:providedBy.

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" : "/makePDG", 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 /makePDG 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 provider according to the SSWAP Protocol for a sswap:Provider<ResourceURI> is the URL where the PDG is to be hosted. For provider properties, only a name property is required; e.g.:

    "sswap:name" : "My Provider name"

/makePDG will automatically construct other aspects of the protocol.  If a PDG claims ownership of a service that is not a subpath of itself (i.e., the URL specified by the sswap:providesResource property is not a subpath of the <ResourceURI>), then the RDG (Resource Description Graph) must reciprocate the claim with a sswap:providedBy statement to the PDG. The URL of the sswap:providesResource must resolve to a valid RDG as created by /makeRDG. 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 and are encouraged but not required.  See sswap:Resource and the example below;

6.  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/makePDG

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

To generate a PDG from JSON, the command:

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

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


    "prefix" : {

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

    },


    "iplant:iPlantCollaborative" : {

        "sswap:name" : "The iPlant Collaborative",

        "sswap:oneLineDescription" : "iPlant provider of SSWAP semantic web services",

        "sswap:aboutURI" : "http://www.iplantcollaborative.org"

    }

}

' 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 UNIX based systems. SSWAP uses a highly distributed model of data re-use, thus while it is possible to embedded definitions within the text of an PDG, a stronger model is to place those definitions at web-accessible URIs.  For example, the gramene:resourceProvider could be typed to various classes or given various properties; e.g.:

    "iplant:iPlantCollaborative" : {

        "rdf:type" : [ "myTerms:myFavType1", "yourTerms:yourFavType2" ],

        ...

See  JSON Syntax Summary as referenced in the JSON Format section; also /makeType and /makeProperty. /makePDG 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.


/makePDG is a convenience service to enable a non-semantic JSON specification to generate a semantic SSWAP OWL RDF/XML PDG. Using it guarantees that the resultant PDG 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 PDG that is used by the semantic web service.  It is perfectly acceptable to take an existing PDG (simply do a HTTP GET on the service provider) and edit the RDF/XML directly to define a new service provider. If creating PDG's without the aid of /makePDG, authors should validate the PDG 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 /makePDG returns content (RDF/XML), it is guaranteed to be a valid SSWAP OWL DL PDG. In these cases the HTTP response code is always '200 OK'. If /makePDG 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" and "imports". 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.

/makePDG

/makePDG