API General Usage
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 &.
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.
||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.|
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.
||How many results to show in a List Response
||Which page of results to show|
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 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.
- HTTP/1.1 200 OK
- 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)
- Content-Length: Download size in bytes
- 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)
- 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.
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:
- Status Code (0/1: optional) -> Different from HTTP Response codes.
- Messages (0/n: optional)
- version (1)
The Status Code indicates the recognized error as documented in Error Codes
The Messages indicates the default description of the error. You can render this to your end users if you want.