SPIN Template Service

TopBraid Live provides a built-in service that can be used to call any globally registered SPIN ASK, CONSTRUCT, SELECT, or UPDATE template as a REST service. This is comparable to a SPARQL endpoint, but allows SPIN developers to hide the details of a SPARQL query from the end user.

In order to expose a SPIN template through this service, the template needs to be stored in a file ending with .spin.*, e.g. example.spin.ttl. Note that the graph context must be specified, either as a parameter to the Web service URL (see below) or using a GRAPH statement in the SPARQL query.

The URL of this service is /tbl/template and the following arguments are supported:

• _template - the URI of the SPIN template
• _base (optional) - the base URI or short graph name of the default query graph
• _withImports (optional) - if "true" then the _base will be used with its owl:imports
• _format (optional) - the format (see below)
• _limit (optional): a value for LIMIT
• _offset (optional): a value for OFFSET
• any other - the lexical forms or URI of the values of the declared arguments of the template

The following URL is an example of the syntax using these parameters:

/tbl/template?_template=http://topbraid.org/swa%23GetResourceValues&_base=urn:x-evn-master:schemaexample&resource=http://topbraid.org/examples/kennedys%23Brown

(These example URLs can be executed from a browser when TBC-ME is running using http://localhost:8083...)

Using short graph names

If the Server Configuration setting for TBC-ME defines the short graph name "schemaexample" for urn:x-evn-master:schemaexample, the following format can be used to set the base graph:

http://localhost:8083/tbl/template?_template=http://topbraid.org/swa%23GetResourceValues&_base=schemaexample&resource=http://topbraid.org/examples/kennedys%23Brown&_format=json

To define other short graph names, go to the Server Administration page at /admin (http://localhost/tbl/admin to use TBC-ME as the localhost server)"schemaexample" and go to the Server Configuration Parameters page. In the section named "URI Parameters" define an instance of "Short graph names"

Encoding qname in SPIN Template URLs

Alternatively, it is possible to encode the template and the base graph as part of the URL:

/tbl/template/swa/GetResourceValues/schemaexample?resource=http://topbraid.org/examples/kennedys%23Brown&_format=json

In the syntax above, the first path segment must be the prefix of the template (here: swa), followed by the local name of the template (here: GetResourceValues). If another argument is provided then it must be one of the short graph names configured in the TopBraid Live server configuration parameters. The system will use that graph together with its imports as the default query graph.

All non-optional arguments of the template must have a corresponding value in the template call. If the argument has an XSD datatype, then the literal lexical form of the value must be supplied as argument. If the argument is resource-typed, then the value must be a URI.

SPIN Template response types

The default serialization of SELECT result sets is JSON, following the SPARQL protocol. Note that when you call this service from a web browser's address bar, the mime type will typically be requested as something that includes the string "xml", and in this case it will produce SPARQL XML Results. CONSTRUCT queries are returned in Turtle format by default. Alternatively, the following values can either be supplied in the HTTP request header's Accept parameter or as value of _format:

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.