3
REST JSON API

Linked Data Browsing

1.1
URI Dereferencing

Following the standard practices for Linked Data, we distinguish between a resource and documents about a resource. Identifiers for the resource follow the pattern:

http://{domain}/id/{...}

When you look them up you get redirected to the corresponding document about that thing. The document URL follows the pattern:

http://{domain}/doc/{...}

For example, in our Zones Dataset, the identifier for Macduff is

http://data.smartjourney.co.uk/id/zone/aberdeenshire/macduff

If you put this into your browser you get redirected to an HTML page about Macduff

http://data.smartjourney.co.uk/doc/zone/aberdeenshire/macduff

1.2
Resource Document Formats

You can specify what format you want that document to be in. By default you get HTML in a human-readable form, but you can also ask for the document in one of several RDF formats: RDF/XML, N-triples, Turtle or RDF/JSON.

There are two ways to specify which format you want: you can append a format extension to the URI or you can use the HTTP 'Accept' header. For both of these approaches, you can apply it either to the resource identifier, the .../id/... URI, or the document address, the .../doc/... URI.

Format

Extension

Accept Header

RDF/XML

.rdf

application/rdf+xml

n-triples

.nt

application/n-triples
text/plain

Turtle

.ttl

text/turtle

JSON

.json

application/json

1.3
Ruby Example

Here's an example of dereferencing a URI using the Ruby 'RestClient' library. Similar approaches can be taken in other languages.

This assumes you already have Ruby set up on your system. Also, if you don't already have it, you'll need to install the rest-client gem:

require 'rest-client'
## 1 Specifying the format in an accept header - in this case RDF/XML
# If you're using the accept header, you can directly request the URI.
# This involves two requests, because doing an HTTP GET on the resource identifier gives you a
# 303 redirect to the appropriate document page. RestClient looks after that for you.
puts RestClient.get 'http://data.smartjourney.co.uk/id/zone/aberdeenshire/macduff', :accept=>'application/rdf+xml'
# Note: You can also request the document page directly
puts RestClient.get 'http://data.smartjourney.co.uk/doc/zone/aberdeenshire/macduff', :accept=>'application/rdf+xml'
## 2 Specifing the format as an extension - in this case JSON
# If using an extension, you must request the document page directly
# (as '.json' is not part of the URI)
puts RestClient.get 'http://data.smartjourney.co.uk/doc/zone/aberdeenshire/macduff.json'

1.4
Alternative URLs for convenient browsing

Alongside the definitive URI for a resource, we offer alternative additional URLs for the information about resources that reflects the way we organise the data into datasets and by type. These offer some convenient ways to navigate and access the data.

1.4.1
Datasets

Our 'Travel Zones' dataset has a URI of

http://data.smartjourney.co.uk/id/dataset/zones

but it can also be accessed at:

http://data.smartjourney.co.uk/datasets/zones

1.4.2
List resources of a type

The following URL:

http://data.smartjourney.co.uk/datasets/reports/incident

provides a list of all resources in the 'Reports' dataset which have a type of:

http://{domain}/datasets/{dataset short name}/{type short name}/{resource short name}[.{format}]

1.4.4
Formats

As with the basic Linked Data Browsing, the information about a resource can be retrieved in multiple formats. Add the format extension to the URL or use the HTTP Accept header as explained above.

The list of all resources of a given type in a given dataset, together with the available triples about those resources, can also be retrieved in multiple formats, using the approaches described above. For example (N-triples)

http://data.smartjourney.co.uk/datasets/reports/incident.nt

These results are paged.Use the parameters _page and _per_page to control the paging process, with a maximum page size of 100. See the SPARQL 'Paging' section below for more details.

To get dataset metadata in machine readable formats, you can use the pattern

http://{domain}/datasets/{dataset short name}.[{format}]

1.5
Resources in external domains

When minting URIs to identify resources we want to talk about, the usual Linked Data practice is to create those URIs in a domain you control, so that it is possible to respond to them in the ways described above.

However, there are times when it is useful to hold information about external URIs in a triple store - that is URIs in a domain that we don't control. Information about those URIs can be retrieved using SPARQL, but it's also useful to have a standard URL pattern to access them.

2.3
Named Queries

Named queries can be called via 'shortcut' urls. Available named queries appear on the API tab of the dataset pages.

http://data.smartjourney.co.uk/sparql/query-name.format

2.4
SPARQL Results formats

The available formats depend on the type of SPARQL query. A SPARQL query can be one of four main forms: SELECT, ASK, CONSTRUCT or DESCRIBE

Query Type

Format

Extension

Accept Header

SELECT

xml

.xml

application/xml
application/sparql-results+xml

json

.json

application/json
application/sparql-results+json

text

.text

text/plain

csv

.csv

text/csv

ASK

json

.json

application/json
application/sparql-results+json

xml

.xml

application/xml
application/sparql-results+json

text

.text

text/plain

CONSTRUCT

RDF/XML

.rdf

application/rdf+xml

N-triples

.nt

text/plain
application/n-triples

Turtle

.ttl

text/turtle

DESCRIBE

RDF/XML

.rdf

application/rdf+xml

N-triples

.nt

text/plain
application/n-triples

Turtle

.ttl

text/turtle

2.5
Errors

If you make a SPARQL request with a malformed query to any of the formats above (i.e. not via the HTML form at /sparql, or the in-page SPARQL console), then a blank response will be returned, with HTTP status 400.

Additionally, if you make a request for a CONSTRUCT or DESCRIBE query which returns over 2MB of data, the server will also respond with a 400 status.

2.6
JSON-P

If you're requesting JSON, you can additionally pass a callback parameter and the results will be wrapped in that function. This is useful for getting round cross-domain issues if you're writing JavaScript. For example:

2.7
Paging

The results of SELECT queries through PublishMyData SPARQL endpoints are paged. We take this approach to make sure that queries respond quickly and to avoid queries with very large result sets putting undue load on the server. The maximum number of results per page is 1000. The default for machine-readable formats is 1000 results per page, and for HTML format results is 20 per page. (We are still experimenting with this feature and would welcome your feedback on it.)

There are two parameters that can be added to the URLs described above to control paging. These are:

_per_page: defaults to 10 in the in-page console, 20 on the SPARQL page (at '/sparql'), or 1000 for data-formats. (Maximum of 1000).

_page: defaults to 1.

For example, this query returns all resources of the Interval Type

SELECT * WHERE {?s a <http://purl.org/NET/c4dm/timeline.owl#Interval>}

The results of CONSTRUCT queries are currently limited to 2MB of data triples and we don't do automatic paging. If you have a CONSTRUCT query with a bigger result than that, you'll need to do your own paging using the SPARQL OFFSET and LIMIT keywords.

This sample Ruby code will loop through all pages of the results of a query and combine them into a single array