Creating Web Services with the TopBraid Platform

TopBraid Live (TBL) is TopQuadrant's server platform for semantic data processing and editing. In addition to being the foundation of various out-of-the-box solution packages such as EVN, TopBraid Live can also be used "stand-alone". The features of the platform can be accessed in various ways, for example via a built-in SPARQL end point. In addition to those bundled web services, TopBraid Live can also host any number of custom web services created by users/administrators. This blog entry enumerates a few options on how to create such web services.

Common to all TopBraid custom web services is that they can be called either via GET or POST requests, and that they are created declaratively: the web services are stored in RDF and typically created with TopBraid Composer. This ensures that web services are seamlessly integrated with the data models/ontologies that they expose. Changes to an ontology will automatically update the web services etc. Furthermore, no "programming" in the traditional sense is needed to create those services.

SPARQLMotion

SPARQLMotion is an RDF-based scripting language with a graphical notations. SPARQLMotion scripts are data processing pipelines that can take some input (e.g. web service arguments), import and aggregate data from external sources, perform some processing (SPARQL etc) and export results in various formats. I had written about creating web services as early as 2008 but my colleagues have since then created much better tutorials on this topic. Note that SWP (see below) provides an alternative syntax for exposing SPARQLMotion functionality as web services.

SPIN Templates

In a nutshell, a SPIN Template is a SPARQL query that can take parameters which are mapped to pre-bound variables. A template is a bit like a stored procedure from SQL databases in that it encapsulates a complex query and gives it a name. Here is an example SPIN Template that provides information about the properties of a given class. The class itself comes in as an argument (arg:class) which is mapped to the pre-bound variable ?class in the body of the template.

Any SPIN Template saved in a .spin.* file can be called as a web service, via the tbl/template servlet. The following example calls the template above against the personal test server bundled with TopBraid Composer ME:

http://localhost:8083/tbl/template?
    _template=http://topbraid.org/swa%23GetRelevantPropertiesOfClass&
    _base=http://topbraid.org/examples/kennedys&
    class=http://topbraid.org/examples/kennedys%23Person&
   _format=application/sparql-results%2Bjson

The parameter _base points at the default query graph (if required) and _format can be any of the SPARQL result set formats including CSV, TSV, XML and JSON.

TopBraid 4.3 introduces another simpler result format, called JSON-simple, which is easy to handle by clients. Example output from the query above in JSON-simple is shown here:

[ { "propertyLabel" : "MI" ,
    "propertyURI" : "http://topbraid.org/examples/kennedys#middleInitial" ,
    "rangeURI" : "http://www.w3.org/2001/XMLSchema#string"
  },
  { "propertyLabel" : "alma mater" ,
    "propertyURI" : "http://topbraid.org/examples/kennedys#almaMater" ,
    "rangeURI" : "http://topbraid.org/examples/kennedys#College"
  },
   ...

Also new in TopBraid 4.3 is syntactic sugar that makes the query URLs easier to write:

http://localhost:8083/tbl/template/swa/GetRelevantPropertiesOfClass/kennedys?
    class=http://topbraid.org/examples/kennedys%23Person

More information on this topic can be found in the TBC help, under "TopBraid Live Integration".

SWP Services

SPARQL Web Pages (SWP) is probably best known for its ability to create HTML renderings of RDF data, but it can also produce any other textual serialization including JSON or XML. An SWP web service looks almost like a SPARQLMotion or SPIN template service in that it is a class that declares the arguments as spl:Arguments. However, SWP services also need to declare their result type, e.g. ui:JSON as value of the ui:responseType property. Here is the upper part of an example SWP web service that produces some JSON consumed by the SWA tree component:

(The ui:responseType of that service is "inherited" from the superclass ui:JSONServices.) The actual work that the service has to perform when called is declared in the lower section of that service definition:

This particular service is using some helper template to compute the shortest path from a given node to a given root, and then serializes the whole result set to a JSON array using the built-in helper element swon:RSArray. SWP is much more powerful than SPIN templates because it includes sophisticated control elements such as if-then-else and forEach. Furthermore, SWP services can also include most of the SPARQLMotion modules in a compact textual notation.

To learn more about SWP services, browse through some of the examples bundled with TopBraid. As of TopBraid 4.3 (beta 2), the TopBraid Live Web Services overview page shown below lists all available SPARQLMotion, SPIN or SWP services - the page itself is generated on the fly using SWP:

Saved Searches

TopBraid EVN includes a powerful search form that can be used to filter instances of a given class by some properties, for example to find "All Islands that have a size smaller than 1000 square kilometres":

There is a little Save button under the search form, allowing users to save the current search form so that it can be restored later. As a side effect, any of those saved searches can also be called as a web service with the URL provided by the dialog as shown below:

You can copy and paste the URL of the service from the dialog above, and it may produce any of the standard result formats.