Linked data API

Jeni Tennison, Dave Reynolds, Leigh Dodds




Hit the space bar for next slide
+/- to change font size, left arrow to go back

Context

Architecture

Helping Publishers

Formatting

Querying

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

result-set for query http://epimorph-pubx1.appspot.com/proxy/api/doc/schools?_page=0

http://education.data.gov.uk/id/school/100869

rdf:type school-ont:School
rdf:type school-ont:TypeOfEstablishment_Other_Independent_School
rdfs:label Southwark Small School
school-ont:establishmentStatus school-ont:EstablishmentStatus_Closed
school-ont:typeOfEstablishment school-ont:TypeOfEstablishment_TERM_Other_Independent_School

http://education.data.gov.uk/id/school/100868

rdf:type school-ont:School
rdf:type school-ont:TypeOfEstablishment_Other_Independent_School
rdfs:label Hope Primary School
school-ont:establishmentStatus school-ont:EstablishmentStatus_Closed
school-ont:typeOfEstablishment school-ont:TypeOfEstablishment_TERM_Other_Independent_School

http://education.data.gov.uk/id/school/100867

rdf:type school-ont:School
rdf:type school-ont:TypeOfEstablishment_Other_Independent_School
rdfs:label Alpha Community School At Springfield Methodist Church
school-ont:establishmentStatus school-ont:EstablishmentStatus_Closed
school-ont:typeOfEstablishment school-ont:TypeOfEstablishment_TERM_Other_Independent_School

...

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)

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

Features (2) - filtering

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

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

Description of: http://epimorph-pubx1.appspot.com/proxy/api/doc/schools/secondary/district/Oxford?_sort=schoolCapacity&min-schoolCapacity=1200

Metadata describing the query and source for endpoint /doc/schools/secondary/district/{district}

Sparql query

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

Source

http://services.data.gov.uk/education/sparql

Specification

@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