Notice: The Bookshare API V1 will be sunset on June 30, 2024 and will no longer be available. Partners will need to migrate to API V2 to continue accessing the Bookshare collection after that date. Learn about API V2.

HTTP-based API

The BWS uses a HTTP-based API. URIs are meaningful and for the most part static. They are easy to share. Parameters are specified within the URI’s path, rather than tacked on as a list via ? and &.

Result Format

Results are returned in XML or JSON format. The encoding of the response is UTF-8. The default format is XML, but JSON can be specified by including the format parameter. This parameter can be specified for all requests except download requests.

Parameter	Value	Description
format	Text	Format of the response. Possible values are json or xml . xml is the default so if format is not specified, the result will be xml.

Examples

• https://api.bookshare.org/book/search/potter/format/json?api_key=YOUR_API_KEY
• https://api.bookshare.org/book/search/potter/format/xml?api_key=YOUR_API_KEY

Paging and Limit

Paging and limit can be controlled by appending the page and limit parameters to any request which results in a Book List Response or Periodical List Response. A default page of 1 (first) and limit of 100 are applied if these parameters are not specified. The maximum limit is 250 results; any specified limit over this will be rounded down to 250. Negative pages and limits will be ignored and defaults will be used.

Parameter	Value	Description
limit	Number	How many results to show in a List Response
page	Number	Which page of results to show

Examples

• https://api.bookshare.org/book/isbn/0-262-19502-X/page/10?api_key=YOUR_API_KEY
• https://api.bookshare.org/book/isbn/0-262-19502-X/limit/10?api_key=YOUR_API_KEY
• https://api.bookshare.org/book/isbn/0-262-19502-X/page/10/limit/50?api_key=YOUR_API_KEY
• https://api.bookshare.org/book/isbn/0-262-19502-X/page/10/limit/50?api_key=YOUR_API_KEY

Throttling

The service is throttled to 3 requests a second from a given application. If this isn’t sufficient, please contact us to make special arrangements. Excessive downloading by an end user may result in suspension or termination of service.

Errors

Errors will be returned as a number so that your application built around the BWS can take appropriate action. There is exactly one error code per error condition. Error codes will never be changed or reused.

Responses

HTTP Success Response Codes

• HTTP/1.1 200 OK

HTTP Failure Response Codes

• HTTP/1.1 401 Unauthorized: (Requires user authentication)
• HTTP/1.1 403 Forbidden: (Invalid Login Attempt)
• HTTP/1.1 404 Not Found: (Requested Resource not found)

HTTP Response Headers

Binary Download Response

• Content-Length: Download size in bytes
• Content-Type:
  • application/zip (Default ZIP download)
  • application/bks2 (BKS2 download format if user-account had set this option under their User Preferences in www.bookshare.org)

All other Response

• Content-Type:
  • text/xml; charset=UTF-8 (For XML response)
  • text/json; charset=UTF-8 (For JSON response – not currently supported)

Note: The Content-Size HTTP Header in binary response is now deprecated and will be removed in future Bookshare Service release. Use Content-Length instead.

Bookshare Response Envelope (for both XML and JSON responses)

Each valid web service request processed will provide a response that will be wrapped in “bookshare” envelope. Along with actual response payload, it also contains the following two information:

1. Status Code (0/1: optional) -> Different from HTTP Response codes.
2. Messages (0/n: optional)
3. version (1)

Status Code

The Status Code indicates the recognized error as documented in Error Codes

Messages

The Messages indicates the default description of the error. You can render this to your end users if you want.