API V1.0 to API V2.0 Migration Guide
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.
Introduction
Moving an application from the Bookshare API v1 to v2 will involve some straightforward changes to endpoint URIs and some changes to the general usage of the API, such as paging technique and user authentication. There isn’t a defined order in which changes need to be made, and they can be done in phases if you wish. Once you have implemented an OAuth2 based authentication flow, your app could even go through a hybrid phase of using both API versions since both sets of endpoints will accept an OAuth2 token (more about that below).
The notes below highlight some of the differences to be aware of when transitioning to the new API. Refer to the full reference documentation for detailed information and examples of each endpoint and resource.
Authentication and Authorization
The API v2 uses OAuth2 to define the process for authentication and authorization, which may be the most significant change to how your app operates. The v2 documentation explains the scenarios for user and system interaction that you can choose to support.
In particular, you will need to do two important things:
- Define an endpoint in your app that can be called by Bookshare at the end of the authentication process.
- Register the URI of that endpoint with Benetech before the OAuth2 process will work, since it is used to verify that authentication callbacks from Bookshare are coming from your API key only to avoid someone trying to spoof your app. You can do that by sending an email to partner-support@bookshare.org
Once you have an app endpoint defined and registered you should be able to test out authenticated calls with any of your test accounts. To aid in the transition, the OAuth2 token that you receive from this process can be used with the API v1 as well. Simply send an authorization header with the token as a bearer token (“Authorization: Bearer <token value>”) rather than sending the custom header of v1 (“X-Password:<password hash>”).
Media Types
Note in the Media Types section that all responses come back as JSON and that UTF-8 is the default encoding.
Pagination
The API v2 replaces the “offset” parameter on listings endpoints with a “next” parameter so that paging is one-directional as far as the API is concerned. Any endpoint with more results than the “limit” amount will also have a “next” link item in the JSON that is a full URL that can be used.
User Roles
In the API v1 a user might be an individual member, an organization member or an organizational sponsor. In v2 these same roles are supported but their capabilities are hinted at through a more general mechanism of links and [capabilities] that are in JSON responses. For example, you might infer that a user is an organizational sponsor if they have a “members” link in the JSON resource that is returned from the /myaccount endpoint, and you can use the URL in that members link to get a list of the organization members. Further, the “allows” values in JSON responses are hints for the capabilities that could be offered to this user to make modifications to a resource.
Error Responses
The API v2 does not have custom error codes for error responses. Instead the HTTP status code will convey the general result and the JSON response will have descriptive text about the problem. Note that this is meant for diagnostic use and is not necessarily text meant to be shown directly to users.
Endpoint Mappings
| API V1.0 URI | Details | API V2.0 URI | API V2.0 Documentation |
|---|---|---|---|
| api.bookshare.org/book/isbn/Text | ISBN Lookup | api.bookshare.org/v2/titles?isbn={isbn} | Title Search |
| api.bookshare.org/book/id/Number | Book Id Lookup | api.bookshare.org/v2/titles/{bookshareId}} | Title Metadata |
| api.bookshare.org/book/searchFTS/Text | Full Text Search | api.bookshare.org/v2/titles?keyword={text} | Title Search |
| api.bookshare.org/book/search/title/Text | Title Search | api.bookshare.org/v2/titles?title={title} | Title Search |
| api.bookshare.org/book/search/author/Text | Author Search | api.bookshare.org/v2/titles?author={author} | Title Search |
| api.bookshare.org/book/search/Text | Title/Author Search | api.bookshare.org/v2/titles?keyword={text} | Title Search |
| api.bookshare.org/book/search/since/Date | Date Published Search | api.bookshare.org/v2/titles?sortOrder=copyrightDate&direction=desc | Title Search |
| api.bookshare.org/book/latest | Latest books added to Bookshare | api.bookshare.org/v2/titles?sortOrder=dateAdded&direction=desc | Title Search |
| api.bookshare.org/book/popular | Popular books on Bookshare | The automated popular list is no longer supported. For curated lists: api.bookshare.org/v2/popularLists For automated recommendations: api.bookshare.org/v2/myRecommendations | Popular Lists Recommendations |
| api.bookshare.org/reference/category/list | Category List | api.bookshare.org/v2/categories | Categories |
| api.bookshare.org/book/search/category/Text | Category Search | api.bookshare.org/v2/titles?categories={categories} | Title Search |
| api.bookshare.org/reference/grade/list | Grade List | Not Available | |
| api.bookshare.org/book/search/grade/Text | Grade Search | api.bookshare.org/v2/titles?readingAge={readingAge} | Title Search |
| api.bookshare.org/periodical/id/Number | Periodical Edition Search | api.bookshare.org/v2/periodicals/{seriesId}/editions | Periodical Editions |
| api.bookshare.org/periodical/id/Number/edition/Date/revision/Number | Periodical Edition Lookup | Not Available | |
| api.bookshare.org/periodical/list | Periodical List Search | api.bookshare.org/v2/periodicals | Periodical Search |
| api.bookshare.org/download/content/Number/version/Number | Generally Available Download Request | api.bookshare.org/v2/titles/{bookshareId}/{format} | Title Download |
| api.bookshare.org/download/content/Number/version/Number/for/Text | User Authenticated Download Request | For Books: api.bookshare.org/v2/titles/{bookshareId}/{format} For Periodicals: api.bookshare.org/v2/periodicals/{seriesId}/editions/{editionId}/{format} | Title Download Periodical Download |
| api.bookshare.org/download/member/Text/content/Number/version/Number/for/Text | Organizational Download Request | api.bookshare.org/v2/titles/{bookshareId}/{format}?forUser={user} | Title Download |
| api.bookshare.org/user/preferences/list/for/Text | User Preference List | api.bookshare.org/v2/myaccount/preferences | Account Preferences |
| api.bookshare.org/user/preference/Number/set/Text/for/Text | User Preference Modification | api.bookshare.org/v2/myaccount/preferences | Update Account Preferences |
| api.bookshare.org/user/info/display/for/Text | User Info | api.bookshare.org/v2/myaccount | Account Summary |
| api.bookshare.org/user/history/for/Text | User History | api.bookshare.org/v2/myaccount/history | Account Downloads |
| api.bookshare.org/user/members/list/for/Text | Organizational Member List | api.bookshare.org/v2/myOrganization/members |