Linked data API

This article outlines how and why you might use the linked data API.

What is the Linked Data API?

It is very common for web applications to expose their data via an API, allowing third party developers to integrate new tools or services. However, each web application’s API is subtly different, requiring developers to read documentation or make use of client libraries to put these APIs to work.

Put simply, linked data provides a common blueprint to allow us to share data from multiple applications and vendors over the web via an agreed, common and non-proprietary mechanism. Any site implementing a linked data API allows sharing of data in the same way as other sites that implement to the specification.

The Web enables us to link related documents. Similarly it enables us to link related data. The term Linked Data refers to a set of best practices for publishing and connecting structured data on the Web. Key technologies that support Linked Data are URIs (a generic means to identify entities or concepts in the world), HTTP (a simple yet universal mechanism for retrieving resources, or descriptions of resources), and RDF (a generic graph-based data model with which to structure and link data that describes things in the world).

For more on Linked Data see this FAQ.

Talis Reading Lists conforms to the Linked Data principals as described by Tim Berners-Lee in this design note on theW3C website.

You may find that you need to work around some browser security features when using these APIs. You are strongly advised to call these APIs from a server rather than directly in a browser.

What can it be used for?

The linked data API can be used to get at the data behind virtually all pages and views within the Talis Aspire Reading List system. You can use it to export the data for a list, item, module, acquisitions review or even a user’s My Bookmarks collection.

The potential uses are limitless and you can use it whenever and wherever you need to integrate data from Talis Aspire Reading Lists in another web application or portal.

How do I use the API?

Given the web address (or URI) of an entity, users can simply change the extension at the end of the URI to invoke the API. By default, both RDF/XML and Javascript Object Notation (JSON) output formats are supported.

By default, if no extension is supplied, the user is given the HTML page relating to the entity.

For example:

https://broadminster.rl.talis.com/lists/D88DE48E-130A-3810-A563-FB41933E9A42.json

By default, this will redirect to the normal list view that a user would see.

Instead, to get data only, you can change the .html extension as follows:

For JSON:
 https://broadminster.rl.talis.com/lists/D88DE48E-130A-3810-A563-FB41933E9A42.json
For RDF/XML:
  https://broadminster.rl.talis.com/lists/D88DE48E-130A-3810-A563-FB41933E9A42.rdf

You can try this right now in your web browser by clicking on this link: https://broadminster.rl.talis.com/lists/D88DE48E-130A-3810-A563-FB41933E9A42.json. Depending on your browser, you’ll either see a list of strings in your browser window or be asked to download a JSON file which can be opened in any text editor.  If you are viewing it in your browser you can "view source" to see a more structured output.

All JSON data served from Aspire conforms to the RDF/JSON format.

JSONP

The API supports JSONP to get around Cross Site Scripting issues. You can specify a callback function, using the cb parameter

https://broadminster.rl.talis.com/lists/D88DE48E-130A-3810-A563-FB41933E9A42.json?cb=myCallbackFunction

Other data formats

Some views in Talis Aspire Reading Lists support additional data formats. These are requested in exactly the same way as the RDF/XMLand JSON formats.

• List view: Can also be requested as RIS or CSV. Use .ris or .csv extensions on the end of the list’s URI, or if using content negotiation, “application/x-research-info-systems” or “text/csv” respectively.
• Acquisitions review view: Can also be requested as CSV, using the same method as described above.
• Events feeds: These can be requested as RSS. Use .rss or if using content negotiation, “application/rss+xml”. Try https://broadminster.rl.talis.com/lists/abf203/events.rss

Content negotiation

Talis Aspire Reading Lists also supports content negotiation. Instead of using extensions to denote the format, take the resource URI without an extension, and get your HTTP client to specify Accept headers. If no accept headers are specified, then the software defaults to redirecting to the HTML version.

Who can use the API?

All public pages and views can be requested via the API. Excessive requests will be rate limited though, except by prior arrangement.

Views behind a user login (such as the My Bookmarks view or Acquisitions Review screens) require the user to log in before the linked data API can be invoked.

My HTTPS URL is not in the data?

When Talis Aspire Reading Lists is being served from an HTTPS endpoint, and if you have a custom CNAME setup (e.g. http://readinglists.myuniversity.ac.uk) then the CNAME is known as the Tenancy Base URL and the HTTPS url (which would be something like https://myuniversity.rl.talis.com) is known as the HTTPS Alias. 

When you make an HTTPS request to the linked data API, the data you will see will use the Tenancy Base URL. This is because of the way that Talis Aspire Reading Lists will be using the Tenancy Base URL as part of the identifiers that identify each node in the linked data graph.

This means that any integrations that expect to use HTTPS should be aware that they will need to know both the tenancy Base URL and HTTPS Alias. because if they are constructing identifiers for resources in the graph those functions will need to be using the Tenancy Base URL.

Talis has no plans to change this behaviour as the identifier in the data - although it looks like a URL - is still an identifier. This concept is deeply baked into the way the application is expecting to handle and display data (not just in the APIs).