Skip to content

Home

Jump to bottom Edit New page
Enrico Daga edited this page Mar 24, 2017 · 26 revisions

BASIL is designed as middleware system that mediates between SPARQL end- points and applications.

Overview

Data providers focus on maintenance and evolution of their SPARQL endpoints and data provided. Data consumers use tailored Web APIs as mean to access data. BASIL introduces Web API tailors as a new actor of the process of publishing and consuming data. Tailors model Web APIs for data consumers through API specifications. An API specification defines: a data source, and the portion of data to be returned by the API, and the input parameters. A SPARQL query is the formalisms used to specify input parameters and output data of a single API. Queries are stored in the BASIL middleware. Each time an API is consumed, its query is executed on the related endpoint, then the query result is returned. In addition, tailors can specify views for each Web API. A view is an alternative presentation of an API results based on a template or script1. In a concrete scenario, the Web API tailor can be a member of the data provider organisation that builds APIs for data consumers, which are not SPARQL experienced, or a data consumer who has SPARQL knowledge and prefers to benefit of the advantages of Web APIs.

Example scenario

BASIL provides as a CRUD API over HTTP. To create a new API, users define a SPARQL query. For instance, the following query was modelled for http://data.open.ac.uk/sparql to support a developer requesting to extract a list of open educational resources related to a given qualification.

prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
  prefix podcast: <http://data.open.ac.uk/podcast/ontology/>
  prefix audioboo: <http://data.open.ac.uk/audioboo/ontology/>
  prefix yt: <http://data.open.ac.uk/youtube/ontology/>
  prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
  prefix rkb: <http://courseware.rkbexplorer.com/ontologies/courseware#>
  prefix saou: <http://data.open.ac.uk/saou/ontology#>
  prefix dbp: <http://dbpedia.org/property/>
  prefix media: <http://purl.org/media#>
  prefix olearn: <http://data.open.ac.uk/openlearn/ontology/>
  prefix mlo: <http://purl.org/net/mlo/>
  prefix bazaar: <http://digitalbazaar.com/media/>
  prefix schema: <http://schema.org/>

 SELECT 
  distinct
  (?related as ?identifier)
  ?type
  (str(?label) as ?title)
  (str(?location) as ?link)

  FROM <http://data.open.ac.uk/context/youtube>
  FROM <http://data.open.ac.uk/context/audioboo>
  FROM <http://data.open.ac.uk/context/podcast>
  FROM <http://data.open.ac.uk/context/openlearn>
  FROM <http://data.open.ac.uk/context/course>
  FROM <http://data.open.ac.uk/context/qualification>
  FROM <http://data.open.ac.uk/context/xcri>
  WHERE
  { 
  # TRY: q18, q51, q70, qd, q36, x86, w39, q61, q64
  BIND(iri(concat("http://data.open.ac.uk/qualification/","q18")) AS ?qualification) .
  {
       # related video podcasts
       ?related podcast:relatesToQualification ?qualification .
       ?related a podcast:VideoPodcast .
       ?related rdfs:label ?label .
       optional { ?related bazaar:download ?location }
       BIND( "VideoPodcast" as ?type ) .
     } union {
       # related audio podcasts
       ?related podcast:relatesToQualification ?qualification . 
       ?related a podcast:AudioPodcast .
       ?related rdfs:label ?label .
       optional { ?related bazaar:download ?location }
       BIND( "AudioPodcast" as ?type ) .
     } union {
       # related audioboo posts
       ?related audioboo:relatesToQualification ?qualification . 
       ?related a audioboo:AudioBooPost .
       ?related rdfs:label ?label .
       optional { ?related rdfs:seeAlso ?location }
       BIND( "AudiobooPost" as ?type ) .
     } union {
       # related openlearn units
       ?related a olearn:OpenLearnUnit .
       ?related olearn:relatesToQualification ?qualification  .
       BIND( "OpenLearnUnit" as ?type ) .
       ?related <http://dbpedia.org/property/url> ?location .
       ?related rdfs:label ?label .
     }  union {
       # related youtube videos
       ?related a schema:VideoObject .
       ?related yt:relatesToQualification ?qualification  .
       BIND( "YoutubeVideo" as ?type ) .
       ?related media:download ?location .
       ?related rdfs:label ?label .
     } 
}

The query returns extracts, video, text, audio of current courses that are related to qualifications provided by the Open University (e.g., Master degree in Computer Science). Each qualification has an ID code (e.g., q18).

In order to make the qualification ID an input parameter of the tailored API, the variable ?_qid has been defined. BASIL considers a mapping between API parameters and SPARQL variables by adding a underscore in the begin of the variable name as convention. Details on variable name conventions for parameters mappings are provided in page SPARQL variable naming convention for WEB API parameters mapping.

The creation of the API is performed with a HTTP PUT request to:

http://basil.kmi.open.ac.uk/basil?endpoint=http://data.open.ac.uk/sparql

The query parameter endpoint defines the SPARQL endpoint and the request body contains a SPARQL query that defines the view on the dataset. This operation triggers the generation of a set of resources:

  • /basil/x68shwt3Qw → base resource, redirects to /spec
  • /basil/x68shwt3Qw/api → to retrieve the data
  • /basil/x68shwt3Qw/spec → to get and update the stored query
  • /basil/x68shwt3Qw/explain → to inspect the query after variables substitution
  • /basil/x68shwt3Qw/view → to manage views
  • /basil/x68shwt3Qw/api-docs → to access the Swagger description

BASIL makes available the Swagger documentation of the API as subresource of the API specification. A Web API can be consumed through a HTTP GET in different ways, for example:

  • /basil/x68shwt3Qw/api?qid=q18 # with content negotiation
  • /basil/x68shwt3Qw/api.json?qid=q18 # or .xml, .rdf, .jsonld, .csv, .nt, .ttl, . . .
  • /basil/x68shwt3Qw/api.html-list?qid=q18 # preprocess the output using the html-list view script (see Views)

When the BASIL API receives a tailored API invocation, the value of the parameter qid substitutes the variable ?_qid in the query that will be executed. Then, the result of the query is returned to the data consumer, according to a data format specified through content negotiation.

The supported response formats are plain XML, JSON and CSV without namespaces, for data consumers that are not familiar with Linked Data, and Semantic Web Standards (such as, RDF+XML, N3 and Turtle). Moreover, users can customize the output with user-defined Views using template or scripting languages (Mustache and JavaScript, in the reference implementation).

Public endpoint

Basil is online as a public service at http://basil.kmi.open.ac.uk.

Useful information:

Add a custom footer
Add a custom sidebar
Clone this wiki locally