Discover

Semantic Web HTTP API

The HTTP API (Application Programming Interface) is a web-based interface for generating iPlant Semantic Web Services entry points and documents.

Why is there an HTTP API? iPlant Semantic Web Services uses the W3C recommendations of RDF/XML and OWL.These are the industry standards for encoding semantic data on the web. Yet these standards can be challenging as they present an "impedance mismatch" between web master skill sets and RDF/XML OWL skill
sets.

Who is the audience for the HTTP API? Data and service providers who want to host semantic web services. If you are a "client" -- a user, someone who wants to use semantic web services but does not want to host your own -- then you do not need this section. This section and the HTTP API is to aid data and service providers in making their content available to you.

What does the HTTP API do? The HTTP API allows anyone to send small snippets of JSON (Javascript Object Notation) to our API web addresses and we return for you RDF/XML OWL Semantic Web Services document. JSON is easy, simple, widely-known and broadly adopted. But JSON is not a semantic language. So architecturally we cannot base the system on JSON. We use JSON solely as a "impedance transformer" between an easy, simple to use syntax and the requisite RDF/XML OWL: you send us JSON content according to the syntax described below, and we send you generated RDF/XML OWL. The content is guaranteed to conform to the iPlant Semantic Web Services protocol as described in Architecture 2. In the coming months we will release a discovery entry point that will execute semantic discovery as a service. All services in the HTTP API are RESTful.

What does the HTTP API not do? The HTTP API does not execute your services for you. The HTTP API does not make arbitrary JSON semantically-aware; instead it converts a specific syntax (see below) into the documents you need to host semantic web services.

Is the HTTP API all I need to host semantic web services? No. As a semantic web service provider, when a user makes a request for your data you will need to access your data and return it. The HTTP API is not applicable for this action since that is happening internal to your servers and your data schemas.  To aid in this action, we have a Java API.

Am I reliant on you to host the HTTP API? No. We host the HTTP API as a service to you. We have bundled the API into a .war (Web Archive) file that you may host internally on your servers. If you do that you will not need our servers at all. In addition to the convenient pre-built .war file, all our code is released open-source and available under a generous Creative Commons license. To download, please visit the SourceForge distribution directory for the latest release.

What is basic way to use the HTTP API?  You will be creating a RDF/XML OWL document called a RDG
(Resource Description Framework) along with other supporting documents. The RDG will be hosted on your server: it is you publishing to the world that you are offering a semantic web service. This publishing is done by "annotating" the protocol with properties and types.  In some cases, the properties are part of the protocol (e.g., sswap:name, ssswap:oneLineDescription), in other cases they are specific to you (e.g, mySite:myInputParameter, etc.). Because semantic web services are to be read by anyone on the web, these properties and types are also hosted, by you, as RDF/XML OWL documents. The HTTP API generates these documents for you: you send it JSON per below and it sends you back RDF/XML OWL following the protocol.

OK, I'm ready to learn the HTTP API. What is it? It's easy: it's just six RESTful web entry points:

HTTP API

http://sswap.info/api 

/makePDG Make a PDG (Provider Description Graph): a description of a data or service provider (e.g., an institution, web host, etc.). You need only one of these.
/makeRDG Make a RDG (Resource Description Graph): a description of a semantic
web service. You may have many of these. RDGs are hosted as documents
at your service entry point.
/makeRIG Make a RIG (Resource Invocation Graph): a request to invoke a service.  The URL of the service is the URL of its hosted RDG.
/makeRRG Make a RRG (Resource Response Graph): the response to a request, in the same format as the RIG.
/makeRQG Make a RQG (Resource Query Graph): a request to discover services
based on how they are classified, the type(s) of data they accept,
and/or the type(s) of data they return.
/makeType Make a type (a class).  A type covers both the notion of a concept and a set.  Most OWL DL constructs are supported.
/makeProperty Make a property (a relation).  Properties can have domains and ranges that can invoke inferencing on their subjects and objects.

How do I invoke the HTTP API? To read the manual pages, visit any of the links above. To use the API, POST a JSON document to it. The API has a standard, RESTful mode of operation. The easiest way to POST is to see if your system has a program such as curl or wget. These are simple to use, pre-installed on many systems, and free to download if you do not have them. For example, to use curl on a
Linux-box or Mac, one would enter:
 

curl --data '

<enter JSON in plain text here>

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

Note the single quotes (') surrounding the input text. On some operating systems such as Windows' cmd.exe, the above will not work and you will need to save the input in a file. You can save the JSON in a file and invoke w/ a single command line such as:

  curl --data @<myFilename> http://sswap.info/api/makeRDG

 where you replace <myFilename> with the actual file name and place it right after the @ sign.

To get the JSON schema for automated checking, invoke a HTTP GET with a requested response MIME type of application/json:

 

curl -G -H 'Accept: application/json' http://sswap.info/api/makeRDG

 

Before you begin: the basics of JSON and a few gotchas. JSON is easy to learn: do see http://json.org. JSON (Javascript Object Notation) is often used as data messaging syntax for Javascript. But our use has no Javascript requirement, so you do not need to run or use Javascript to use the HTTP API: simply send the API JSON plain text and it will return to you RDF/XML OWL following the protocol. JSON has the concept of an object, which is a comma-delimited list ofkey:valuepairs, and the concept of anarray, which is a comma-delimited list ofvalues. Objects are demarcated by curly brackets { }; arrays are demarcated by square brackets [ ]. Data is encoded as strings or values (see http://json.org). Congraulations: you now know about 90% of JSON. Now the gotchas:

  1. JSON is sensitive to syntax: one misplaced comma (or even whitespace in some parser settings) and it all collapses.Use a validator such as JSLint and/or JSONLint before sending to the HTTP API, because if it is not valid JSON, it ain't gonna work.

  2. No comments.  JSON has no mechanism for embedding comments; everything in JSON is considered data.

  3. Objects cannot have duplicate keys.  Keys are always strings (not other values, including arrays); keys cannot be lexically duplicated. Values can be duplicated and of mixed type. So { "myID" : 1, "yourID" : 1, "thisData" : [ 1, 2, "three" ] } is valid, but { "a" : 1, "a" : 2 } is not. For
    the latter case, we combine objects and arrays in a syntax as: { "a" : [ 1, 2 ] }.

An example: Creating a PDG (Provider Description Graph) Try constructing the following PDG.  You'll note how the properties follow the protocol:

curl --data '
{
"prefix" : { "gramene" : "http://sswap.gramene.org/vpin/" },
"gramene:resourceProvider" : {
"sswap:name" : "Gramene",
"sswap:oneLineDescription" : "A Resource for Comparative Grass Genomics",
"sswap:aboutURI" : "http://www.gramene.org/qtl",
"sswap:providesResource" : "gramene:qtl-by-linkage-group"
}
}
' http://sswap.info/api/makePDG

 We note the following constructs:

  • The JSON content is itself a single object, thus everything is bounded within an outermost opening curly bracket { and a closing curly
    bracket }.

  • The API accepts four keys words, of which one is shown above ("prefix").  The key words are "prefix", "imports", "mapping", and "definitions". The value of each key word is an object that allows you to define:

    • "prefix": Define a short-hand tag or prefix that can be used to abbreviate a URL.  This enables a QName-like capability common in OWL and XML.

    • "imports": On processing, read in the RDF/XML file at the given URL. This enables an owl:imports capability common in OWL.

    • "mapping": Designate how the service maps its input to its output. Includes typing as well as 1:1, 1:*, *:1, and *:* mappings.

    • "definitions": Define input and output nodes

  • The URL of the provider ("gramene:resourceProvider") begins the Provider's definition.  Some properties are required, some are optional; you can always add your own properties. See the protocol at SSWAP Provider for details.

What do you do with the above document once the RDF/XML is returned from the /makePDG API? Host it on your web site at the URL corresponding to "gramene:resourceProvider".  Of course, unless you are Gramene, you'll replace the prefix "gramene:" and the URL with your own web address.  A security check is enforced that will not allow you to claim the Providers' of others, so the URL of the Provider must match the document URL from where it is hosted.

An example: Creating an RDG (Resource Description Graph) Try constructing the following RDG.  Here too it follows the protocol:

curl --data '
{
"prefix" : {
"gramene" : "http://sswap.gramene.org/vpin/",
"grqtl" : "http://sswap.gramene.org/vpin/ontologies/qtl/",
"qtl" : "http://sswapmeet.sswap.info/qtl/"
},

"gramene:qtl-by-linkage-group" : {
"sswap:name" : "Gramene QTLs for Linkage Group Retrieval",
"sswap:oneLineDescription" : "Given an input linkage group returns list of qtl accessions and published name",
"sswap:providedBy" : "gramene:resourceProvider",
"sswap:aboutURI" : "http://www.gramene.org/qtl",
"sswap:metadata" : "gramene:qtl-by-linkage-group-metadata.txt",
"sswap:inputURI" : "gramene:invoke-qtl-by-linkage-group.jsp"
},

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

"definitions" : {
"_:subject" : { "rdf:type" : "grqtl:QtlByLinkageGroupRequest" },
"_:object" : { "rdf:type" : "qtl:QTL" }
}
}
' http://sswap.info/api/makeRDG

The above introduces the place-holder nodes "_:subject" and "_:object" in a 1:1 mapping under the "mapping" section.  Then in the "definitions" section it defines the nodes as belonging to specific types. Subjects can have 1:many mappings by using the JSON array [ ] syntax for objects:

 

"mapping" : { "_:subject" : [ "_:object1", "_:object2" ] },

and multiple subjects can be listed within the "mapping" object to create many:many mappings.  Hint: keep it simple; a lot can be achieved with a 1:1 mapping by adding properties to the subject, so only use more complicated mappings in advanced cases.

The JSON above uses properties and types.  These too are RDF/XML OWL documents; they have URLs, and when hosted on the web they make themselves available to anyone. Thus hosting not only makes terms and their definitions available to automated reasoners when they interact with your service, but builds a marketplace for use and reuse and seeds the ground for integration. Use the HTTP API calls /makeProperty and /makeType to make these and other component pieces.  More details are discussed in the JSON Syntax page. Like PDGs, the RDG must be hosted at the URL given in the RDG. For more on creating an RDG and all the API calls, see http://sswap.info/api.

What to do next? The HTTP API helps you create RDF/XML OWL documents that semantically describe your offering; these documents are hosted on your web site. The next step is to actually perform the service and make your service discoverable to the world. To semantically wrap your service we have a Java API. To make it discoverable, iPlant will be hosting a Discovery Server based on the research running at http:/sswap.info.  To publish your service without waiting for a production Discovery Server, publish at http://sswap.info/publish.jsp.

Resource Invocation Graphs (RIGs) are virtually identical to RDGs, but with properties and values added as needed to invoke the service. In most cases, client tools will create RIGs based on the RDF/XML OWL obtained from dereferencing a desired service's RDG, but we include a /makeRIG API entry point for completeness. Resource Query Graphs (RQGs)are similar, except here the types and properties are used to discover services. RQGs are discussed with respect to Semantic Searching and also in our publication Gessler et. al 2009.

JSON SyntaxA detailed description of the input format is described on the JSON Syntax page. The JSON syntax allows one to express OWL concepts in JSON. In practice, services can be described using only a little OWL; thus the OWL support evident in the JSON syntax should be seen as a depth of support for the OWL expert, not as the minimum required for the casual developer. For an primer on OWL, see the OWL 2 Primer.

Where to go from here: