Skip to main content
Sign in MENU

Item linking API

Tim Hodson
  • Updated

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.

Your library systems vendor may be able to incorporate this API to allow a check and alert that a resource that is about to be withdrawn is on your reading list.

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.

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:

https://broadminster.rl.talis.com/isbn/9780230272316/lists

https://broadminster.rl.talis.com/isbn/9780230272316/lists.json

The following JSON data is returned:

{
"http://demo.talisaspire.com/lists/34848A4A-52AE-CAC0-7591-DD145241C9D3": "Arts Reading List ",
"http://demo.talisaspire.com/lists/D88DE48E-130A-3810-A563-FB41933E9A42": "Climate Change: Impact and Implications"
}

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:

https://broadminster.rl.talis.com/doi/10.1108/13666282200900003/lists.json

https://broadminster.rl.talis.com/lcn/000045294/lists.json

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:

https://broadminster.rl.talis.com/isbn/9780230272316/lists.json?cb=foo

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

foo({
"http://demo.talisaspire.com/lists/34848A4A-52AE-CAC0-7591-DD145241C9D3": "Arts Reading List ",
"http://demo.talisaspire.com/lists/D88DE48E-130A-3810-A563-FB41933E9A42": "Climate Change: Impact and Implications"
});

Who can use this API?

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

Typical Implementation

These steps outline the typical way in which this API might be used.

  • The library catalogue which the user is using has an area where custom functionality can be inserted using javascript.
  • The user is viewing a resource such as a book in a library catalogue.
  • The user will see additional information to tell them that the resource appears on a reading list.
  • The javascript code will:
    • Build a URL as outlined above which includes the LCN or ISBN or DOI of the resource being viewed. It will typically specify a callback function, and make a non blocking asynchronous JSONP request.
    • If the request to the API returns a 404 NOT FOUND, then there are no lists with that resource on. Exceptions should be handled graceful and not block or halt other javascript code that may be running on the page.
    • If the item does exist, the typical implementation will provide a clickable link to take the user to the list.
  • It should be expected that there could be many results returned. In the case of popular study resources, these may appear on many hundreds of lists.

Notes

  • Private lists will be included in the results, but students will need to log in to the university IDP before they can access. If coming from the learning system, students are already logged in and this is transparent to them.
  • Private lists cannot be excluded from the results.
  • Talis can enable an option to limit the results to only time periods which are currently marked as active. Active time periods are the ones which show in the time period selection box when editing the list details.

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/.

The University of Sussex

Tim Graves at the University of Sussex used this API to add 'cited on' links to their Primo Explore catalogue.

The University of Auckland

Eric Johnston at the University of Auckland uses the API when they receive turnaway messages for limited user e-books to check if the ebook is on a reading list. The API is used as part of a Chrome extension called Context Menu Search, which allows you to select an LCN in a catalogue record and insert it into the API string to perform the search.

Related articles