Context

• UK government commitment to Linked Data
• not just downloads
• programmatic access to data
• "Just give us CSV"
• alien data model
• alien querying method
• alien formats
• Possible answers
• custom APIs over databases
• customisable middleware over linked data

Architecture

Helping Publishers

• Automatic APIs
• create linked data
• provide SPARQL endpoint
• deploy API middleware
• Customisable URI patterns
• easy access to common queries
• easy to add
• support experimentation

Formatting

• What's wrong with existing formats?
• ugly and hard to read
• require custom parsers
• generate alien data models
• Simple publishing formats
• retain linked data roots
• remove round-tripping requirement
• represent rooted graph
• JSON and XML

Querying

• Need to create lists
• SPARQL is too complex
• understanding of data model
• understanding of syntax
• understanding of vocabulary
• URI-based querying
• sorting, paging
• filtering, viewing

How it works

Processing model

Specifying an endpoint

API on a sparql source

spec:api1 a api:API;
    api:sparqlEndpoint 
        <http://services.data.gov.uk/education/sparql>;
    api:endpoint spec:schools  .

An endpoint for the API

spec:schools
    a api:ListEndpoint;
    api:uriTemplate "/doc/schools";
    api:selector [
    	api:type school-ont:School;
    ] ;
    api:defaultViewer spec:viewerDefault;
    api:viewer spec:viewerDefault, spec:viewerMedium .
   

A minimal view

spec:viewerDefault a api:Viewer;
        rdfs:label "default";
        api:properties (rdf:type rdfs:label 
             school-ont:establishmentStatus school-ont:typeOfEstablishment) .
  

Using it

View schools:

/doc/schools

Returns results

Or in RDF (Turtle)

View schools:

/doc/schools.ttl

Returns results

<http://epimorph-pubx1.appspot.com/proxy/api/doc/schools?_page=0>
      a       api:Page ;
      openSearch:itemsPerPage      "10"^^xsd:long ;
      openSearch:startIndex        "1"^^xsd:long ;
      api:page      "0"^^xsd:long ;
      api:pageSize "10"^^xsd:long ;
      dct:isPartOf
              <http://epimorph-pubx1.appspot.com/proxy/api/doc/schools> ;
      xhtml:first
         <http://epimorph-pubx1.appspot.com/proxy/api/doc/schools?_page=0> ;
      xthml:next
         <http://epimorph-pubx1.appspot.com/proxy/api/doc/schools?_page=1> ;
      api:contains (<http://education.data.gov.uk/id/school/100869> ... ) .

<http://education.data.gov.uk/id/school/100869>
      a  school-ont:TypeOfEstablishment_Other_Independent_School , school-ont:School ;
      rdfs:label "Southwark Small School" ;
      school-ont:establishmentStatus
              school-ont:EstablishmentStatus_Closed ;
      school-ont:typeOfEstablishment
              school-ont:TypeOfEstablishment_TERM_Other_Independent_School .

school-ont:School
      rdfs:label "School" .

school-ont:TypeOfEstablishment_TERM_Other_Independent_School
      rdfs:label "Other Independent School" .

school-ont:EstablishmentStatus_Closed
      rdfs:label "Closed" .
  

Features (1)

• returns a list of resources (with descriptions) not a set of "bindings"
• helps to reinforce the resource-centric nature of linked data
• open ended, can request everything known about the listed resources
  /doc/schools.json?_view=all
• paged, with links to nearby pages
• multiple formats via suffix, query parameter or conneg
• including web-friendly JSON format

JSON format

View schools:

/doc/schools.json

Returns results

{
  "format":"linked-data-api",
  "version":"0.1",
  "results":[
    {
      "_about":"http://localhost:8081/sdx-ui/sdx/api/doc/schools?_page=0",
      "contains":[
        {
          "_about":"http://education.data.gov.uk/id/school/100000",
          "establishmentStatus":{
            "_about":"http://education.data.gov.uk/def/school/EstablishmentStatus_Open",
            "label":"Open"
          },
          "label":"Sir John Cass's Foundation Primary School",
          "type":[
            { "_about":"http://education.data.gov.uk/def/school/School",
              "label":"School"
            },
            { "_about":"http://education.data.gov.uk/def/school/TypeOfEstablishment_Voluntary_Aided_School",
              "label":"Voluntary Aided School"
            }
          ],
          "typeOfEstablishment":{
            "_about":"http://education.data.gov.uk/def/school/TypeOfEstablishment_TERM_Voluntary_Aided_School",
            "label":"Voluntary Aided School"
          }
        },
        ...
      ],
      "first":"http://localhost:8081/sdx-ui/sdx/api/doc/schools?_page=0",
      "isPartOf":"http://localhost:8081/sdx-ui/sdx/api/doc/schools",
      "itemsPerPage":10,
      "next":"http://localhost:8081/sdx-ui/sdx/api/doc/schools?_page=1",
      "page":0,
      "pageSize":10,
      "startIndex":1,
      "type":"http://www.epimorphics.com/vocabularies/api#Page"
    }
  ],
  "context":{ ... }
}

JSON format

• simple, "natural" structure - resources as objects, lists as arrays
• resource and resource values have full URI
• but properties abbreviated to simple labels
• uniform tree structure, even if that means duplication
• context element gives mapping information
• allows inversion of mapping for "well-behaved" RDF
• documents what the labels mean, so you can discover the full URIs
• documents the available vocabulary to assist follow up query creation

Features (2) - filtering

• Filtering uses same simple property labels as JSON, URIs not required

Narrow to schools providing nursery:

/doc/schools ? nurseryProvision=true & _view=medium

Note that API has to know that nurseryProvision is a boolean valued property.

Narrow to schools dealing with secondary education using a path expression:

/doc/schools ? phaseOfEducation.label=Secondary & _view=medium

Alternatively use name-phaseOfEducation

/doc/schools ? name-phaseOfEducation=Secondary & _view=medium

• Can also test for existence/absence of value, or value range

E.g. limit to schools with size > 1200:

/doc/schools ? min-schoolCapacity=1200

Sublists and patterns

Package useful filters into endpoints, with inheritance

E.g. create a sub-list for secondary schools

Map /doc/schools/secondary to all schools with name-phaseOfEducation=Secondary:

spec:schoolsSecondary
    a api:ListEndpoint;
    api:uriTemplate "/doc/schools/secondary";
    api:selector spec:schoolsSecondarySelector;
    api:defaultViewer  spec:viewerMedium .       
    
spec:schoolsSecondarySelector a api:Selector;
    	api:type school-ont:School;
    	api:query "name-phaseOfEducation=Secondary" .

View schools:

/doc/schools/secondary

Can use patterns in URL to supply the filter values

E.g. all secondary schools in some administrative district:

spec:schoolsSecondaryDistrict
    a api:ListEndpoint;
    api:uriTemplate "/doc/schools/secondary/district/{district}";
    api:selector [
        api:parent spec:schoolsSecondarySelector;
    	api:query "name-districtAdministrative=?district";
    ] ;
    api:defaultViewer  spec:viewerMedium .     

Use that to get the secondary phase schools in Oxford:

/doc/schools/secondary/district/Oxford

Help with formulating queries

• filter syntax in queries can be used directly in new specifications
• JSON context field tells you properties you could filter on
• auto-inclusion of labels enables filter-by label
• inspect the SPARQL generated for the query

../meta/doc/schools/secondary/district/Oxford ? min-schoolCapacity=1200 & _sort=schoolCapacity

@prefix api:     <http://www.epimorphics.com/vocabularies/api#> .

<http://epimorph-pubx1.appspot.com/proxy/meta/doc/schools/secondary/district/Oxford?_sort=schoolCapacity&min-schoolCapacity=1200>
      <http://www.w3.org/2000/01/rdf-schema#comment>
              "Metadata describing the query and source for endpoint /doc/schools/secondary/district/{district}" ;
      api:endpoint <http://www.epimorphics.com/examples/specSchools#schoolsSecondaryDistrict> ;
      api:listURL <http://epimorph-pubx1.appspot.com/proxy/api/doc/schools/secondary/district/Oxford?_sort=schoolCapacity&min-schoolCapacity=1200> ;
      api:sparqlEndpoint <http://services.data.gov.uk/education/sparql> ;
      api:sparqlQuery """SELECT ?r WHERE {
?r <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>  <http://education.data.gov.uk/def/school/School> .
?r <http://education.data.gov.uk/def/school/phaseOfEducation>  ?___0 .
?___0 <http://www.w3.org/2000/01/rdf-schema#label>  'Secondary' .
?r <http://education.data.gov.uk/def/school/districtAdministrative>  ?___1 .
?___1 <http://www.w3.org/2000/01/rdf-schema#label>  'Oxford' .
?r <http://education.data.gov.uk/def/school/schoolCapacity>  ?___2 .
?r <http://education.data.gov.uk/def/school/schoolCapacity>  ?___3 .
 FILTER (?___3 >= '1200'^^<http://www.w3.org/2001/XMLSchema#int>) }  ORDER BY ?___2  OFFSET 0 LIMIT 10""" .

 ...

Summary

• Helping consumers
• simple JSON (and XML) formats as well as RDF syntaxes
• reduces barriers to using the data
• no need for RDF code libraries
• simple filtering and variable views
• reduces barriers to querying
• no need to learn SPARQL
• stepping stone to linked data world
• retain concept of resources with URIs
• look at the SPARQL you made
• Helping publishers
• make linked data publishing worthwhile
• easy deployment of APIs