Skip to main content
Sign in MENU

Bookstore API specification

Tim Hodson
  • Updated

This article specifies a simple REST-based service that booksellers can implement in order to provide Talis Aspire Reading Lists with information about items that they sell.

Introduction

Talis Aspire Reading Lists (TARL) is a resource (i.e. reading) list solution used by a significant proportion of UK Universities. See www.talis.com for our current customer base.

TARL allows academics to collect resources from around the web including books, articles, journals, websites, podcasts, videos, etc. The academic then organises these into a list, which is published for students.

The student can browse their list, and drill down on any resource to uncover more information, such as library availability and purchase options. These are provided through the use of a bookseller widget, configured on a customer by customer basis.

By default, this is set to Amazon but it can be configured using the specified API to work with local campus bookstores or other University endorsed booksellers to deliver local availability as well as online purchase choices.

The figure below shows an example of the bookstore widget within Talis Aspire at the University of Kent (in this case, for Blackwell).

Principles_of_Sports_Marketing___University_of_Kent.png

Specification

The bookseller is expected to implement this API so that Talis can easily query for bookseller availability and pricing information.

The API is used whenever a student views an item detail page in their reading list. The API is not used to harvest data, and responses are not cached.

Authentication

If use of the API needs to be tracked, then we can support this. The API should provide a mechanism for passing a pre shared access key in the URL.  Requests can be either HTTP or HTTPS.

We are unable to support OAuth at this time.

Request

Talis Aspire will make a GET request to an endpoint structured as follows:

GET http:// <hostname>/<servicename>/<isbn>?branchid=<branchId>

For example this could be:

GET http://www.jscampus.co.uk/item/9781847873002
GET http://www.jscampus.co.uk/item/9781847873002?branchid=12345

The branchid parameter is optional and allows booksellers to provide results from one of their specific branches, for example the branch located on the Campus.

Response

A successful request for an item with an isbn of “9781847879066” would look like this:

**Response Header should be set to 200 OK.**
**Response Body should contain:**
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<items>
  <item isbn="9781847879066">
    <detailPageURL>http://www.jscampus.co.uk/shop/product_display.asp?ProductID=9781847879066</detailPageURL>
    <availability>In Print</availability>
    <stockStatement>Available to order as a special interest title - may take up
    to 4 weeks</stockStatement>
    <format>Hardback</format>
    <price>90.00</price>
    <currency>GBP</currency>
    <title>Discovering Statistics Using SPSS</title>
    <author>Field, Andy</author>
    <publisher>SAGE Publications Ltd</publisher>
    <publishedDate>20090301</publishedDate>
  </item>
</items>

If the item has a book jacket image then the response should include the URL we can use to render the image for example:

<jacketImage>
  http://www.jscampus.co.uk/NielsonImages/9780201699715.jpg
</jacketImage>

A successful request for an item with an ISBN of “9781847879066”, that is also available in other formats would look like the example below. We know which item we originally requested details for, so we will make the assumption that any additionally defined items in the response exist because they are variations by format.

**Response Header should be set to 200 OK.**
**Response Body should contain:**
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<items>
  <item isbn="9781847879066">
    <detailPageURL>http://www.jscampus.co.uk/shop/product_display.asp?ProductID=9781847879066</detailPageURL>
    <availability>In Print</availability>
    <stockStatement>Available to order as a special interest title - may take up
    to 4 weeks</stockStatement>
    <format>Hardback</format>
    <price>90.00</price>
    <currency>GBP</currency>
    <title>Discovering Statistics Using SPSS</title>
    <author>Field, Andy</author>
    <publisher>SAGE Publications Ltd</publisher>
    <publishedDate>20090301</publishedDate>
  </item>
    <item isbn="9781847879073">
    <detailPageURL>http://www.jscampus.co.uk/shop/product_display.asp?ProductID=97
    81847879073</detailPageURL>
    <availability>In Print</availability>
    <stockStatement>In Stock</stockStatement>
    <format>Paperback</format>
    <price>34.99</price>
    <currency>GBP</currency>
    <title>Discovering Statistics Using SPSS</title>
    <author>Field, Andy</author>
    <publisher>SAGE Publications Ltd</publisher>
    <publishedDate>20090301</publishedDate>
  </item>
  <item isbn="9781847872975">
    <detailPageURL>http://www.jscampus.co.uk/shop/product_display.asp?ProductID=97
    81847872975</detailPageURL>
    <availability>In Print</availability>
    <stockStatement>Low Stock</stockStatement>
    <format>Paperback</format>
    <price>32.99</price>
    <currency>GBP</currency>
    <title>Discovering Statistics Using SPSS eBook</title>
    <author>Field, Andy</author>
    <publisher>SAGE Publications Ltd</publisher>
    <publishedDate>20090301</publishedDate>
  </item>
</items>

Notes on response fields

It is worth noting the following for some elements in the XML response.

element note
<detailPageURL> This is for the ‘Buy it now’ button. If you have an affiliate scheme then we would expect to wrap any clicks to this link within an appropriate affiliate URL
<price> This is the price of the item but without currency symbols. This value will be used as is
<currency> This is the three letter code for the currency. e.g. GBP, USD, AUD, NZD, EUR
Other elements These will be shown to the user as is, and may be hidden if the UX design of the area using this content changes.

Response Codes

If we make a request for details about an item that your implementation of this service has no knowledge of then:

**Response Header should be set to 404 Not Found.**
**Response Body should be empty**

If we a make a request that contains errors and cannot be parsed by your implementation of this service then:

**Response Header should be set to 400 Bad Request.**
**Response Body should be empty**

In the event that your implementation does not support querying at branch level, and a branch id is specified in the request:

**Response Header should be set to 501 Not Implemented.**
**Response Body should be empty**

In the event that your implementation does support querying at branch level, but the branch id specified is not recognised:

**Response Header should be set to 400 Bad Request.**
**Response Body should be empty**

In the event that the service has been taken down for maintenance:

**Response Header should be set to 503 Service Temporarily Unavailable.**
**Response Body should be empty**

Finally in the event that some other internal issue has prevented the service from completing the request:

**Response Header should be set to 500 Internal Server Error.**
**Response Body should be empty ** 

Related articles