Item linking API

The item linking API allows you to answer the question “Which lists have this resource on it?”

What is the Item linking API?

The item linking API allows you to discover where an item is used within Talis Aspire. Suppose you have a book with a given ISBN, and you want to find out which lists in Talis Aspire reference the book. You can do that with the item linking API.

What can it be used for?

You could use this API to extend your library OPAC or discovery tool, building a widget that shows which lists items are on.

This API is used within Talis Aspire Reading Lists itself to provide the “Check which other resource lists this item is on” function from the acquisitions review screen.

The API can be configured to only show lists for the current time period. If you would like this feature turned on then please raise a support ticket.

How do I use the API?

To use the API, all you have to do is build a special URI. Given this URI, Talis Aspire Reading Lists will return a set of list names and URIs in JSON format.

The API supports ISSN, ISBN10, ISBN13, local control numbers/catalogue IDs (LCN) or DOIs. Put simply, start with one of these, and then build it into the URI used to call the API. Let’s try an example with ISBN “0596000278”:

To call the API use either of the following two URIs:

http://lists.broadminsteruniversity.org/isbn/0596000278/lists

http://lists.broadminsteruniversity.org/isbn/0596000278/lists.json

The following JSON data is returned:

{
"http://lists.broadminsteruniversity.org/lists/481C9869-3B9A-F011-F4BD-9FA76E464904": "Copy of new list with import citations",
"http://lists.broadminsteruniversity.org/lists/DDDA8DC1-703C-A6DA-4BF7-4B81B08FB436": "new list with import citations"
}

NB: This API handles ISBN10 to ISBN13 conversion for you. So, a request for the ISBN10 “0070167265” will also return matches for 9780070167261. There is no need to do two calls (they will return exactly the same results).

Here are some other examples, using DOI and LCN (note that both of these will give a valid 404 response):

http://lists.broadminsteruniversity.org/doi/10.1111/j.1540-5885.2012.00964.x/lists.json

http://lists.broadminsteruniversity.org/lcn/586124/lists

What if there are no lists found for the identifier given?

You will get a HTTP 404 NOT FOUND response. Any application that you develop using this API should expect to handle the 404 as a valid response condition meaning that the Talis Reading Lists tenancy did not contain any data which matched that requested.

The callback parameter and JSONP

If the API is called from Javascript within the browser, you’ll need to use a JSONP callback parameter to avoid the cross-domain scripting security model. For more information on JSONP, see this Wikipedia article.

The API supports the query string parameter “cb” to specify the callback function. The callback function must be a valid function in your calling code that will handle the JSON data returned on a successful request. For example:

http://lists.broadminsteruniversity.org/isbn/0596000278/lists.json?cb=foo

Wraps the response as a parameter of the “foo” method:

foo({
"http://lists.broadminsteruniversity.org/lists/481C9869-3B9A-F011-F4BD-9FA76E464904": "Copy of new list with import citations",
"http://lists.broadminsteruniversity.org/lists/DDDA8DC1-703C-A6DA-4BF7-4B81B08FB436": "new list with import citations"
});

Who can use this API?

Anyone can use this API, although excessive requests will be rate limited though, except by prior arrangement.

Examples of this API in use

Nottingham Trent University

Richard Cross at NTU has developed RELIC (REsourceListItemChecker) to help with the item acquisitions process. The service makes use of this API to show which lists an item is on within NTU’s Talis Aspire Reading Lists implementation. See http://www.urko.org.uk/library/rlms/relic/.

Manchester Metropolitan University

Mark Stubbs at MMU has used this API alongside the List-Linking API as part of their Learning Management System integration - find out more here.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk