Release Notes

/v2/titles/:bookshareId : GET includes new fields and links:

/v2/titles/:bookshareId : GET includes new listing of the following accessibility metadata response fields per format:

W3C EPUB Accessibility Documentation

W3C Accessibility Properties Crosswalk

ONIX Codelist 196

The "/v2/myaccount" and "/v2/mylists" endpoint prefixes are deprecated. The new endpoint addresses start with "/v2/myAccount" and "/v2/myLists", using camel-casing as other endpoints do. There is not a defined end-of-life yet for the deprecated endpoints. The API documentation now refers to the new names.

Updated the authentication documentation to include an OAuth guide for mobile developers.

/v2/myHighlights : POST to store a highlight in a title of a given format.

/v2/myHighlights : GET to retrieve highlights in a title of a given format.

/v2/myHighlights : DELETE to delete a highlight in a title of a given format.

/v2/myHighlights : PUT to update a highlight in a title of a given format.

/v2/myBookmarks : GET API docs updated to include the "start" and "limit" parameters.

"Download a title file resource" added param 'speed'. This can be used to control the playback speed of MP3 files.

Password length is clarified to include the maximum length allowed.

/v2/myBookmarks : DELETE to remove a bookmark from a given title.

"Get my account preferences" added response field 'showRecommendations'. This can be used to determine if you want to receive personalized recommendations.

"Update my account preferences" added param 'showRecommendations'. This can be used to update your preference in regards to receiving personalized recommendations.

"Get user account preferences" added response field 'showRecommendations'. This can be used to determine if a user wants to receive personalized recommendations.

"Update user account preferences" added param 'showRecommendations'. This can be used to update a user’s preference in regards to receiving personalized recommendations.

/v2/myBookmarks : GET to return the bookmarks for a given title.

/v2/myRecommendations: GET to return personalized book recommendations.

/v2/myBookmarks : POST to store a bookmark for a given title.

/v2/popularLists/:popularListId : GET Retrieve the most popular titles in the Most Popular list with the given id.

"Search for titles" Added param 'includedBisacHeadings'. This will limit results to those titles with a BISAC heading that matches or starts with one of the values provided.

"Search for titles" Added param 'excludedBisacHeadings'. This will limit results to those titles with a BISAC heading that does NOT match or start with one of the values provided.

"Search for titles" Added param 'includedBisacCodes'. This will limit results to those titles with a BISAC code that matches exactly one of the values provided.

"Search for titles" Added param 'excludedBisacCodes'. This will limit results to those titles with no BISAC codes that match one of the values provided.

/v2/popularLists : GET Retrieve Most Popular lists.

Reading Position "dateAdded" now has earliest recorded activity timestamp for that title.

BISAC code values are correctly returned in "Search for titles" endpoint.

Reading Position "dateModified" has most recent activity timestamp for that title.

/v2/bisacCodes : GET Retrieve a list of BISAC category codes that are used by the system.

/v2/myReadingPosition/:bookshareId/:format : GET Retrieve reading position for a specific title format for the current user.

The reading list title resource now includes cover image links.

The user account resource now includes "grade".

General Reference, Search for titles : GET Added param 'originCountry'. This will limit results to those that originated from the given country.

/v2/lists : GET Retrieve a list of reading lists whose name or description matches the given keyword.

Live title count endpoint has been fixed to address issues with the count not displaying properly for some users.

General Reference, Live title count : GET Added new params 'includeShared' and 'country'.

(Auth) - /oauth/revocations : Will revoke an OAuth2 access token.

General Reference, Add active periodical : POST Changed param from 'bookshareId' to 'editionId'. The 'bookshareId' param, however, will continue to be accepted in place of the 'editionId' param.

Membership, Add active periodical for a user : POST Changed param from 'bookshareId' to 'editionId'. The 'bookshareId' param, however, will continue to be accepted in place of the 'editionId' param.

The 'includedContentWarnings' property of the recommendation profile is deprecated, and will be removed in a future release. Any current values for existing users have been removed.

Added enum option of 'marrakeshPartner' to the proofSource parameter for the following Membership Assistant endpoints:

The "marrakeshPODException" property has been added to the title_metadata_detail resource.

Collection Management, Update book metadata : PUT will accept a new "marrakeshPODException" boolean parameter.

/v2/readingEvents : POST will create reading activity events that mark different types of reading activity.

The "packagingStatus" property for active titles has been deprecated, since titles will no longer be packaged when they are added to an active books or active periodicals list.

The active title resource now includes a "fileResourceStatus" property to represent the readiness of the particular format chosen for an active title to be able to provide file resources.

The "Create user for organization" endpoint for Sponsors, at /v2/myOrganization/members, no longer has a "proofSource" parameter, and "disabilityType" is optional. The proof source is automatically "school verified."

The "Create user for organization" endpoint for Membership Assistants, at /v2/organizations/:id/members, no longer requires "disabilityType" or "proofSource". The proofSource will default to "school verified" if it is not specified when disabilityType is provided.

Submit Metadata For New Title endpoint now requires the "externalFormat" parameter.

Get My Organization Members endpoint documentation now includes the "next" token in the response description.

Get My Account Downloads endpoint documentation now includes the "start" parameter in the request description, and includes a realistic "dateRequested" in the sample response structure.

Get Periodical Editions endpoint documentation now includes the "start" parameter in the request description.

Filtering titles at the /v2/catalog endpoint by startUpdatedDate or endUpdatedDate will return the correct range of titles.

Download history records available from /v2/myaccount/history now return the date a title was requested in addition to the date that that the packaged title was downloaded. This allows a user to see when they accessed a book, even if they have yet to actually download it.

/v2/periodicals/:seriesId/editions/:editionId : (Collection Assistant) DELETE will remove an edition of a periodical from the collection.

Searching for titles with the 'externalIdentifierCode' parameter now correctly finds matching titles.

An incorrect value for the 'start' parameter of a search request now correctly returns a 400 status code.

Editing periodical series metadata now supports more properties:

Editing periodical edition metadata now supports more properties:

Title searches and catalog searches that have paged far into a large result set should no longer time out.

Download requests return a 429 status when there are too many requests for a single user active at a time.

Catalog search (/v2/catalog) supports the "titleStatus" parameter to let you filter for just live or just withdrawn titles.

The reference documentation for API endpoints is split from one page into three pages:

OAuth authorization flow preserves authorization codes during the token creation process.

Title search that specifies a country restriction correctly filters results to include only titles available in that country.

OAuth authorization now supports client secrets. Clients without a secret are still supported, but we will be transitioning away from that for clients that are able to protect a secret, primarily those that are not in browser-based apps.

OAuth tokens can be used until they expire, even if a new access token is created from a refresh token. Previously, using the refresh token to get a new access token would expire the previous one.

Editing title metadata now supports more properties:

The date-related fields in resource responses have been changed to return timestamp information in GMT timezone, rather than just calendar dates. The format is the "Complete date plus hours, minutes and seconds", as described in the reference on dates. This change allows API clients to provide users with accurate event dates in their local time, such as subscription start and end dates, and download history dates. There are two date fields that were not changed:

Deprecated: the "status" property of the title_download resource, replaced with "packagingStatus" and "downloadStatus", to represent download requests that do not involve packaging by our system. In these cases packagingStatus is null, whereas downloadStatus always has a value.

Active titles and active periodicals lists now include values for the "size" property. This allows users or clients to gauge the resource cost of downloading or streaming a particular title.

User subscriptions that are created without specifying a downloadLimit now correctly get the default download limit defined for the chosen subscription type.

Download requests for formats in which a title is not available now correctly return a 400 response code.

Title metadata update (PUT /v2/titles/:id) supports making changes to BISAC categories, via the "bisacCategories" request parameter. Along with this, the category resource that is returned as part of the title metadata for various endpoints now includes a "code" property that contains the BISAC code value (e.g. "FIC002000"). Previously, the category resource would just describe the category name (e.g. "FICTION / Action & Adventure"). For categories that are not BISAC, the code value will be empty.

/v2/titles : (Collection Assistant) POST will submit metadata for a new title to the collection, associated with the same site as the submitter. There is a required minimal set of metadata, and a larger set of supported metadata. No file attachment is supported yet, but will be coming in the future.

Titles that are not live in the collection (i.e. withdrawn titles, or submitted but still waiting for required metadata to be supplied) can no longer be added to reading lists.

Title metadata includes values for a new 'externalFormats' parameter, representing formats not delivered by the system but meaningful for a particular site.

Title search supports values for the new 'externalFormats' parameter, to filter results to only those which match the values given.

Title metadata update (PUT /v2/titles/:id) supports parameters for a variety of different contributor types (editor, arranger, translator, etc). The values provided will overwrite any existing values on the title for the given contributor type.

Deprecated: the "status" property of the active_book resource, replaced with "packagingStatus" and "downloadStatus", to allow a process status for content that is requested but never packaged by the system. In these cases packagingStatus is null, whereas downloadStatus always has a value.

Deprecated: the "copyright" property of title_metadata_detail and title_metadata_complete, replaced with "copyrightHolder".

Deprecated: the "usageRestrictionId" property of usage_restriction, replaced with "restrictionCode" to represent a human-meaningful value.

/v2/titles/:id : (Collection Assistant) PUT is now supported to update the metadata of a title. In this first release, you are able to submit changes to properties that have simple types (string, integer, boolean) and multi-valued types (languages, grades, etc). More title properties will be supported in the future.

The title search endpoint has an "authorFilter" parameter that allows you to limit the results of a search to those with an exact match on the value. This is different than searching by "author", where the search will try matching using partial or fuzzy matches.

Membership Assistants of certain sites are able to add titles to a member’s active books list, where the title may not have an electronic artifact in the collection. These types of titles can not be "downloaded", but they will show up for a member on their active books list, and on their account history list.

/v2/titles/:id/history : (Collection Assistant) Retrieve the list of processing events for a given title. These can tell you when a title first arrived in the system, when different metadata values were edited, and when derived artifacts were created or changed, as well as by whom.

The "next" link on periodical edition lists is now available, to allow paging through a set of editions.

The title search endpoint has a new parameter, "excludeGlobalCollection", that can be used to limit results to only those titles that are associated with the same site as the requesting user. By default, or with this parameter set to false, search results may include titles that are freely available or that have been designated as shareable from other sites.

The "format" parameter for title searches has been deprecated, and replaced by the "formats" parameter. This new parameter can appear multiple times to allow filtering the results by multiple formats.

/v2/myMessages : Retrieve and mark as read the messages available to the current user.

/v2/messages : (Membership Assistant) Create, retrieve and expire individual messages for any user account associated with the same site, or system messages for all site users.

/v2/myMessages : Retrieve a set of messages for the current user. Future support will be added to mark messages as read, and to remove them before their expiration date.

/v2/messages : (Membership Assistant) POST endpoint to create a new message, either directed to a single user or to all members of the site.

Keyword search now uses the current user’s language preference to rank search results.

Error response message text is now correct when creating a user without an email address.

File resource requests for books or periodicals now perform content negotiation to determine whether the response will be gzip compressed or not, based on the 'Accept-Encoding' request header contents. For better performance, clients should send 'Accept-Encoding: gzip' whenever possible.

/v2/accounts/:userIdentifier/lists : (Membership Assistants) Retrieve and create reading lists owned by a specific user of the same site.

/v2/myaccount/recommendationProfile : Retrieve and update the properties of the current user’s recommendation profile, which includes author, category and content warning settings. This complements the support for Membership Assistants that was added in 5.6.11.

Endpoints which accept strings that contain commas no longer treat the value as multiple values, but rather a single value. For example, searching for titles in the category "Cooking, Food and Wine" will now look for titles in one category, rather than looking for categories "Cooking" and "Food and Wine".

/v2/lists/:id/titles : GET, POST and DELETE support was expanded to allow Membership Assistants to view titles of, add titles to, and remove titles from, a reading list if it is owned by a member of the same site.

/v2/titles/:bookshareId/:format/resources : Retrieve a list of file resources that make up the artifact of the given format, akin to a manifest. This endpoint was released as a demonstration in 5.6.10, and now returns real values.

/v2/titles/:bookshareId/:format/resources/:resourceId : Retrieve a single file resource. This endpoint was a released as a demonstration in 5.6.10, and now returns a real value.

/v2/myActiveBooksProfile : Added a new property, "requestList", that can be assigned a value of any reading list which the user can view. It will represent a source of books that can be added to the users active books list when that list has space available.

/v2/accounts/:userIdentifier/activeBooksProfile : The same property, "requestList", is available to Membership Assistants.

/v2/myPeriodicals : GET supported to retrieve the list of periodical subscriptions of the current user, and POST supported to subscribe to a periodical.

/v2/myPeriodicals/:seriesId : DELETE supported to unsubscribe from a periodical.

/v2/accounts/:userIdentifier/periodicals : (Membership Assistants) Same as /v2/myPeriodicals, but for any specified user of the same site.

/v2/accounts/:userIdentifier/periodicals/:seriesId : (Membership Assistants) Same as for /v2/myPeriodicals/:seriesId, but for any specified user of the same site.

/v2/accounts/:userIdentifier/recommendationProfile : (Membership Assistants) Retrieve and update the properties of the given user’s recommendation profile, which includes author, category and content warning settings.

/v2/accounts/:userIdentifier/preferences : (Membership Assistants) PUT support added to complete the support for user preferences. Users have been able to view and update their own preferences, but Membership Assistants could only view them.

/v2/myActiveBooksProfile : Retrieve and upate the properties of the current user’s active books profile, which includes settings for how to deliver books to the user’s active books list. This complements the support added in 5.6.10 for a Membership Assistant to perform these actions.

The sample API calls in the reference documentation no longer have places where the "roles" property in a response has blank names, such as [ "individual", "" ].

A new property, "readingAge", was added to the resource at /v2/accounts/:userIdentifier/activeBooksProfile and /v2/myActiveBooksProfile.

/v2/accounts/:userIdentifier/activeBooksProfile : (Membership Assistants) Retrieve and update a user’s settings for the selection of books to be added to their active books list. The GET request returns a resource of three groups of properties:

/v2/titles/:bookshareId/:format/resources : Retrieve a list of file resources that make up the artifact of the given format, akin to a manifest. This endpoint is currently a demonstration only, and returns a set list of files. It is slated to be completed in the near future.

/v2/titles/:bookshareId/:format/resources/:resourceId : Retrieve a single file resource. This endpoint is currently a demonstration only, and returns a set file. It is slated to be completed in the near future.

/v2/organizations/:id/members : (Membership Assistants) Retrieve an organization’s roster of members. This allows Membership Assistants to do the same thing that Sponsors could do with a GET request to /v2/myOrganization/members.

/v2/myOrganization/members : POST supported for Sponsors to add new members to their organization. This allows Sponsors to do the same thing that Membership Assistants could do with a POST request to /v2/organization/:id/members.

Reference documentation updates to clarify the requesting user for "Assigned Titles" endpoints, and to have a consistent description of the "user identifier" parameter to "Membership Assistant - User Accounts" endpoints.

The search results from /v2/titles have additional properties in them which were formerly only in requests for title metadata:

Deprecated: Individual contributor type records in title metadata. They will be represented as elements of a "contributors" resource, as a "contributor" resource with a type.

Deprecated: brailleGrade values of "grade_1" and "grade_2" on PUT requests to /v2/myaccount/preferences are deprecated in favor of "uncontracted" and "contracted". This will make the values consistent with brailleGrade that is used in artifact metadata. The values for brailleGrade on GET requests to /v2/myaccount/preferences will now be "uncontracted" or "contracted".

Deprecated: grade property of "uniqueID". The new field "gradeCode" will provide a better reference for allowable values based on the ONIX standard (for US grades) and the BIC group (for UK grades).

Narrator type was defined as allowing the values "human" and "tts" (all lower case), when used as a title search filter, and as "Human" (initial caps) or "TTS" (all upper case) when appearing in artifact metadata. The parsing of title search parameters actually only accepted "HUMAN" or "TTS" (all caps). This has been changed to use and accept the values as lower case in both input and output.

Narrator gender was defined in the spec as "Male", "Female" or "Other" (initial caps) when appearing in artifact metadata. In order to be consistent with other controlled vocabulary values, the values are now lower case, "male", "female", and "otherNonBinary".

/v2/organizationTypes : (Membership Assistants) Retrieve a list of possible organization types that can be used when creating a new organization. The list will be specific to the site of the user making the request

All of the contributors associated with a title will be included in an array of "contributors" in the title metadata resource.

Contributor names will be represented with two properties, "displayName" and "indexName", rather than the name piece properties such as they are in resources like "author" (i.e. first, middle, last, prefix, suffix). This should make it clearer what the full name display is intended to be (displayName), and what the name is sorted by in the datastore (indexName).

The "userAccount" resource now includes a "userIdentifier" property that can be used when needing to refer to a specific user, when acting as a Membership Assistant or Sponsor. Endpoints which accept a username as the user identifier will now also accept the "userIdentifier" string. For example, a Membership Assistant could ask for an account summary by "/v2/accounts/username@someplace.org" or by "/v2/accounts/<user identifier>".