Penguin Random House Developer Blog
RSS FeedEnhanced API v1.2.26 released
On Thursday June 22, 2017, version 1.2.26 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.
Version 1.2.26 release notes
The /works/views/list-display representation contains two different ISBN fields, one is part of the frontlistiest object and the other is just called isbn. The frontlistiest object is always the frontlistiest title of the work (i.e. seq=1) regardless of what title filters have been specified as part of the request. On the other hand, the isbn element contains a member of the title family that also satisfies all of the specified fllter conditions. We got a request to return the on-sale date that corresponds to isbn and I immediately regretted the choice to not make isbn an object like frontliestiest is. So while we've left isbn as-is, we've added a new element called representative that has the same structure as frontlistiest but which contains the same ISBN as isbn as well as its on-sale date.
/domains/PRH.US/works/views/list-display?workId=228566&format=TR
"frontlistiest": { "isbn": 9780449015131, "onsale": "2013-09-24" }, "representative": { "isbn": 9780763687649, "onsale": "2016-09-13" }, "isbn": 9780763687649,
UK titles (i.e. domains PRH.UK, RH.UK and PDK.UK) now have proper cover computed for some (though not all) endpoints.
/domains/PRH.UK/titles/9781783445295
{ "rel": "icon", "href": "http:\/\/rhdam.randomhouse.co.uk\/getimage.aspx?cat=default&class=books&type=jpg&mode=&size=origjpg&id=243428", "method": "GET", "parameters": null },
There was a new content field added to MyHouse called PRODUCT_FEATURE that is now available as part of /titles/{isbn}/content. It has also been exposed in the /works/{workId}/views/product-display view as part of the additionalText element.
/domains/SALESPLATFORM/titles/9780553212563/content
"product_feature": "This is sample content, sample content, sample content, sample content, sample content, sample content, sample content, sample content<\/b>, sample content, sample content, sample content, sample content, sample content, sample content, <i>sample content, <\/i>sample content, sample content, sample content, 2017-06-15 18:22:04 * Stuff about this book - Stuff about this book Sample content man oh man",
New Feature
Task
Enhanced API v1.2.25 released
On Monday June 12, 2017, version 1.2.25 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.
Version 1.2.25 release notes
A new feature exposing additional promotional images was added to both the /works/views/product-display and /search/views/search-display endpoint. It is a hash mapping the image type to a list of promo image objects.
For the /works listing, the element additionalPromoImages is added to each Title object and is always populated.
/domains/PRH.US/works/208913/views/product-display
"additionalPromoImages": { "14": [ { "copyright": null, "imagename": "9780375869020_3068.pdf", "photocredit": null, "photocaption": null, "photodate": null, "releasedB2B": null, "releasedB2C": "2017-03-24", "promoImageUrl": "https:\/\/images.randomhouse.com\/promo_image\/9780375869020_3068.pdf" } ], "19": [ { "copyright": null, "imagename": "9780375869020_3067.pdf", "photocredit": null, "photocaption": null, "photodate": null, "releasedB2B": null, "releasedB2C": "2017-03-24", "promoImageUrl": "https:\/\/images.randomhouse.com\/promo_image\/9780375869020_3067.pdf" }, { "copyright": null, "imagename": "9780375869020_3069.pdf", "photocredit": null, "photocaption": null, "photodate": null, "releasedB2B": null, "releasedB2C": "2017-03-24", "promoImageUrl": "https:\/\/images.randomhouse.com\/promo_image\/9780375869020_3069.pdf" } ] },
For the /search listing, it is only conditionally populated it populatePromoImages=true is passed. Because it is attached at the work level, the hash of image types to image listings is further mapped by ISBN.
/domains/PRH.US/search/views/search-display?q=wonder&populatePromoImages=true
"additionalPromoImages": { "9780375869020": { "14": [ { "copyright": null, "imagename": "9780375869020_3068.pdf", "photocredit": null, "photocaption": null, "photodate": null, "releasedB2B": null, "releasedB2C": "2017-03-24", "promoImageUrl": "https:\/\/images.randomhouse.com\/promo_image\/9780375869020_3068.pdf" } ], "19": [ { "copyright": null, "imagename": "9780375869020_3067.pdf", "photocredit": null, "photocaption": null, "photodate": null, "releasedB2B": null, "releasedB2C": "2017-03-24", "promoImageUrl": "https:\/\/images.randomhouse.com\/promo_image\/9780375869020_3067.pdf" }, { "copyright": null, "imagename": "9780375869020_3069.pdf", "photocredit": null, "photocaption": null, "photodate": null, "releasedB2B": null, "releasedB2C": "2017-03-24", "promoImageUrl": "https:\/\/images.randomhouse.com\/promo_image\/9780375869020_3069.pdf" } ] } }
New Feature
- [RHAPI-651] - Expose RHCB Resources to API
Enhanced API v1.2.24 released
On Wednesday June 7, 2017, version 1.2.24 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.
Version 1.2.24 release notes
A new parameter was added, showFirstReleases, that can be used with the /titles endpoint to restrict the ISBNs that are returned to those that match the on-sale date of the work parent.
/domains/PRH.US/titles?divisionCode=12&showFirstReleases=true
For the BOT site, some additional data was added to the /titles representation when the parameter populateBestsellerPos is supplied. Because this information is sensitive, it is only available to Internal clients and is not supported for the regular public endpoint. In addition some new sort parameters were added that also have restricted access. For full details, see the ticket RHAPI-646.
For the sales sites, a new parameter, coverColor, was added to filter titles based on the new data available in the MYH_COVER_COLOR table. For details on how to use this parameter, see the ticket RHAPI-693.
Finally, the view /authors/views/list-display had its representation extended to include the first and last components of the author being returned.
New Feature
- [RHAPI-682] - Add new showFirstReleases parameter
Task
Enhanced API v1.2.22 released
On Friday May 12, 2017, version 1.2.22 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.
Version 1.2.22 release notes
This release had three bug fixes. One was to the view /works/{workId}/views/also-in/author
where the seriesList element was not being populated. Another was where the rows parameter was not being respected when a list of isbn values was being passed to the /titles
endpoint and a sort was specified. Finally there was a bug fix that manifested when we tried to release that was related to debugging code not visible to the end user.
There were also various new features introduced with this release. Note that we're a bit inconsistent with our JIRA tickets so some are called Tasks while others are called New Features but really for the purposes of these notes, they are all new features.
First we added a new parameter called showTopselling for the sales sites. This is a boolean filter that is designed specifically for four different sales websites. It has very little general utility because A) it is based on a site-specific query that is run nightly against Netezza to pull sales in certain channels and B) it requires a siteFilter with one of the values:Retail, Christian, Catholic or HomeSchool.
Second, we added some new elements to the /titles response: binding (a code/description object) and editionId. Both are UK-only elements so for US and CA titles, they will be NULL or zero.
"binding": { "code": null, "description": null }, "editionId": 0,
Third, we added two new views to support the ISTCA app: /works/views/istca
and /titles/views/istca
.
/domains/PRH.US/works/views/istca?workId=50612
{ "status": "ok", "recordCount": 1, "startTimestamp": "2017-05-16T08:43Z", "endTimestamp": "2017-05-16T08:43Z", "timeTaken": 8, "data": [ { "workId": 50612, "title": "Dark Places", "author": "Gillian Flynn", "coverUrl": "https://images.randomhouse.com/cover/9780307341570", "earliestOnSale": "2009-05-05", "formats": [ "DN", "CD", "EL", "TR" ], "divisions": [ "Crown/Archetype", "Audio" ] } ], "error": null, "params": { "domain": "PRH.US", "workId": "50612", "clientGroup": "Public" } }
/domains/PRH.US/titles/views/istca?isbn=9780307341570
{ "status": "ok", "recordCount": 1, "startTimestamp": "2017-05-16T08:46Z", "endTimestamp": "2017-05-16T08:46Z", "timeTaken": 5, "data": [ { "isbn": 9780307341570, "isbnHyphenated": "978-0-307-34157-0", "workId": 50612, "title": "Dark Places", "author": "Gillian Flynn", "onSaleDate": "2010-05-04", "exportOnSaleDate": null, "format": "Trade Paperback", "subformat": null, "binding": null, "trim": "5-3/16 x 8", "edition": "0", "price": 15.00, "coverUrl": "https://images.randomhouse.com/cover/9780307341570", "seq": null } ], "error": null, "params": { "isbn": "9780307341570", "domain": "PRH.US", "clientGroup": "Public" } }
Finally, we added a new view for the sales sites called /works/views/sales-display that performs a number of different queries under the hood to return Title objects (the same as /titles) but with the cardinality of /works. It uses logic to select a representative ISBN that satisfies all of the supplied criteria and then either considers frontlistiest ordering or topselling order (same as showTopselling above) to select which ISBN is representative within the work.
/domains/SALESPLATFORM/works/views/sales-display?catUri=/art-techniques&catSetId=S1&siteFilter=Retail
Bug
- [RHAPI-661] - /works/#####/views/also-in/author endpoint does not return seriesList data
- [RHAPI-672] - Titles request to the API returning more than I expected
- [RHAPI-684] - Error produced by author display view
New Feature
- [RHAPI-675] - Add showTopselling filter parameter
- [RHAPI-678] - Add TITLE fields binding and edition_id
Task
Enhanced API v1.2.19 released
On Thursday February 2, 2017, version 1.2.19 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.
Version 1.2.19 release notes
This release has three minor bug fixes.
Library Thing weights
Category sets such as BISAC ('BI') or Consumer ('CN') relate to ISBNs with an integer that indicates sequencing (as indicated by the seq element). Library Thing ('TA') categories also have an integer associated with the ISBN joins but rather than indicating sequencing, that value actually indicates weight. Previously this value had been passed along in the same seq element but it was pointed out that this behavior produced a problem when you tried to list all the Library Thing categories of a particular work. The query that is generated selects the smallest of all seq values among the ISBNs of that work with that category but with weights we would prefer to sum the possible values.
Therefore in this release, we've separated the Library Thing weights into a separate field and exposed sort=weight as a new sort option.
/domains/BOT/works/108336/categories?catSetId=TA&sort=weight&dir=desc
"categories": [ { "catId": 90000035069, "description": "fantasy", "catUri": null, "menuText": null, "hasChildren": false, "seq": 0, "weight": 3259, "_embeds": null, "_links": [ ] }, { "catId": 90000034177, "description": "epic", "catUri": null, "menuText": null, "hasChildren": false, "seq": 0, "weight": 288, "_embeds": null, "_links": [ ] }, { "catId": 90000074123, "description": "a song of ice and fire", "catUri": null, "menuText": null, "hasChildren": false, "seq": 0, "weight": 278, "_embeds": null, "_links": [ ] }, { "catId": 90000034143, "description": "dragons", "catUri": null, "menuText": null, "hasChildren": false, "seq": 0, "weight": 246, "_embeds": null, "_links": [ ] }, { "catId": 90000034979, "description": "epic fantasy", "catUri": null, "menuText": null, "hasChildren": false, "seq": 0, "weight": 230, "_embeds": null, "_links": [ ] }, { "catId": 90000034340, "description": "war", "catUri": null, "menuText": null, "hasChildren": false, "seq": 0, "weight": 152, "_embeds": null, "_links": [ ] }, { "catId": 90000035000, "description": "medieval", "catUri": null, "menuText": null, "hasChildren": false, "seq": 0, "weight": 138, "_embeds": null, "_links": [ ] }, { "catId": 90000035097, "description": "politics", "catUri": null, "menuText": null, "hasChildren": false, "seq": 0, "weight": 131, "_embeds": null, "_links": [ ] }, { "catId": 90000034980, "description": "high fantasy", "catUri": null, "menuText": null, "hasChildren": false, "seq": 0, "weight": 114, "_embeds": null, "_links": [ ] }, { "catId": 90000034076, "description": "adventure", "catUri": null, "menuText": null, "hasChildren": false, "seq": 0, "weight": 113, "_embeds": null, "_links": [ ] } ],
The other two bug fixes are minor tweaks to parameter interpretations around a /works listing with rows=0 and a list of specific ISBNs and the other around the behavior of showBoxBundles=false.
Bug
Enhanced API v1.2.13 released
On Thursday November 17, 2016, version 1.2.13 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.
Version 1.2.13 release notes
This release has several minor enhancements.
Additional promo image fields
The first relates to promo images and includes a couple new fields (releaseB2B and releaseB2C) as well as a link added to be able to fetch the indicated image.
/domains/PRH.US/titles/9780307269942/promoimages
"promoImages": [ { "promoImageId": 2809, "category": "5", "contributor": null, "copyright": null, "imageName": "9780307269942_1287.jpg", "videoLink": null, "photoCredit": null, "photoDate": null, "photoCaption": null, "releaseB2B": null, "releaseB2C": "2009-04-23", "_links": [ { "rel": "icon", "href": "https:\/\/images.randomhouse.com\/promo_image\/9780307269942_1287.jpg", "method": "GET", "parameters": null } ], "_embeds": null },
Handling empty results
The next change involves a new parameter, returnEmptyLists, which takes a boolean 'true' or 'false' and alters how the API handles 404 results. For example, this request for the e-book version of work ID #12 normally returns a 404.
/domains/PRH.US/works?workId=12&format=EL
{ "code": 404, "message": "Not found", "request": { "method": "listWorks", "parameters": { "domain": "PRH.US", "workId": "12", "format": "EL", "clientGroup": "Public" }, "url": "http:\/\/api.penguinrandomhouse.com\/resources\/v2\/title\/domains\/PRH.US\/works" }, "exception": null }
However if we specify returnEmptyLists=true, then we'll get back a 200.
/domains/PRH.US/works?workId=12&format=EL&returnEmptyLists=true
{ "status": "ok", "recordCount": 0, "startTimestamp": "2016-11-17T12:43Z", "endTimestamp": "2016-11-17T12:43Z", "timeTaken": 4, "data": [ ], "error": null, "params": { "domain": "PRH.US", "workId": "12", "format": "EL", "clientGroup": "Public" } }
More filters
The sales platform requested that we add some more filters and so we've added filter parameters ignoreDivisionCode, ignoreSaleStatus and ignoreSalesRestriction. In addition we've created a new parameter called siteFilter though it is still in development and not currently ready to be used. Basically the idea with that is that the Common Reads site wanted to be able to use an existing domain that contains a superset of all the titles they want to display. Further, they are developing a standard set of filters that they will want applied to *all* the calls being made from that site. Since it would be cumbersome to try to maintain that filter list separately on each different call for the site, I agreed to take a copy of those filters in JSON form and add it to the API configuration under the key "CommonReads". Then what we can do is expose to them this siteFilter parameter such that when they append '&siteFilter=CommonReads' to their calls, it will automatically add all of those configured filters to the call. Like I said, this is not completed yet and when we have a better working example of this feature, I will demonstrate it in the release notes. If you have need of this kind of functionality or think it would aid your development, get in touch with the API team and we can discuss adding a site filter specific to your site as well. Using these site filters helps to limit the explosion of site-specific domains.
Other changes
There are a few other miscellaneous changes as well. Of those, the only one relevant to our users is that the views also-purchased and matches-on-tag can now be filtered by formatFamily
Bug
- [RHAPI-606] - Please add two new UK domains
New Feature
- [RHAPI-597] - Add three new ignore parameters: divisionCode, saleStatus, salesRestriction
- [RHAPI-604] - Add parameter so that empty lists return 200 instead of 404
- [RHAPI-605] - Add support for formatFamily parameter to matches-on-tag and also-purchased views
Task
- [RHAPI-598] - Add Common Reads guides (new promo images) into product-display
Sub-task
- [RHAPI-600] - Add two fields to ISBNxPROMOIMAGE in datamover
Enhanced API v1.2.12 released
On Friday November 4, 2016, version 1.2.12 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.
Version 1.2.12 release notes
This is a minor release that adds a number of data elements to existing endpoints to support the Common Reads site under development.
Task
Enhanced API v1.2.11 released
On Thursday September 29, 2016, version 1.2.11 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.
Version 1.2.11 release notes
Several bugs around predictive search were addressed with this release. In addition a new endpoint /awards was added to return a list of awards for a list or set of titles or works.
Bug
- [RHAPI-568] - Predictive search returns incorrect recordCount
- [RHAPI-571] - Start parameter not working for predictive search
- [RHAPI-579] - predictive search can repeat documents
- [RHAPI-580] - search display view should not allow negative start value
New Feature
- [RHAPI-573] - Add /awards endpoint
Task
Enhanced API v1.2.10 released
On Thursday August 11, 2016, version 1.2.10 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.
Version 1.2.10 release notes
This is a minor release with a couple of new features added to support the Books on Tape site. The Title representation gained two audio fields, projectedMinutes and audioPackage while the listing gained a new sort option, "format" which orders the elements by format code. This use case for this sort option is with the /works/{workId}/titles resource where the different titles of a work will be ordered by format code.
Prior to the 1.2.10 release, there were a couple emergency releases that got version numbers 1.2.8 and 1.2.9.
New Feature
- [RHAPI-565] - Add "projected_minutes" and "audiopackage" to Title representation
Task
- [RHAPI-564] - Add "sort=format" option to title listings
Enhanced API v1.2.7 released
On Thursday July 7, 2016, version 1.2.7 of the Enhanced PRH API was released to production. If you encounter any problems with your applications as a result of these changes, please contact us at api@penguinrandomhouse.com.
Version 1.2.7 release notes
This is a minor release that exposes two new resources /properties and /subseries to support development of the kids sites.
Properties and Subseries endpoints
For many kids books, in addition to specifying a series, it is possible for the publisher to identify a subseries or specific propertyName for an ISBN. Therefore when taking a comprehensive approach to grouping kids books, one needs to consider all three of these fields. In order to make it possible to correctly list and group titles by these groupings, we added support for these new endpoints and subresources.
/domains/PRH.US/properties?suppressLinks=true
"properties": [ { "propertyName": "Arthur (TM)", "_links": [ ], "_embeds": null }, { "propertyName": "Barbie", "_links": [ ], "_embeds": null }, { "propertyName": "Beauty and the Beast", "_links": [ ], "_embeds": null }, { "propertyName": "Big Time Rush", "_links": [ ], "_embeds": null },
/domains/PRH.US/subseries?suppressLinks=true
"subseries": [ { "subseries": "14 Days in Shonan", "_links": [ ], "_embeds": null }, { "subseries": "A Bedtime Board Book", "_links": [ ], "_embeds": null }, { "subseries": "A Berenstain Bears Help Bk(TM)", "_links": [ ], "_embeds": null }, { "subseries": "A Chunky Flap Book(TM)", "_links": [ ], "_embeds": null },
These endpoints can also be specified as subresources to answer questions such as, "What are the properties of author #3496?" or "What are the subseries of work #219531?"
/domains/PRH.US/authors/3496/properties
{ "status": "ok", "recordCount": 1, "startTimestamp": "2016-07-07T14:54Z", "endTimestamp": "2016-07-07T14:54Z", "timeTaken": 4, "data": { "properties": [ { "propertyName": "Arthur (TM)", "_links": [ { "rel": "self", "href": "https:\/\/api.penguinrandomhouse.com\/title\/client\/Public\/domains\/PRH.US\/properties\/Arthur%20(TM)", "method": "GET", "parameters": null }, { "rel": "https:\/\/api.penguinrandomhouse.com\/title\/authors\/definition", "href": "https:\/\/api.penguinrandomhouse.com\/title\/client\/Public\/domains\/PRH.US\/properties\/Arthur%20(TM)\/authors", "method": "GET", "parameters": null }, { "rel": "https:\/\/api.penguinrandomhouse.com\/title\/titles\/definition", "href": "https:\/\/api.penguinrandomhouse.com\/title\/client\/Public\/domains\/PRH.US\/properties\/Arthur%20(TM)\/titles", "method": "GET", "parameters": null }, { "rel": "https:\/\/api.penguinrandomhouse.com\/title\/works\/definition", "href": "https:\/\/api.penguinrandomhouse.com\/title\/client\/Public\/domains\/PRH.US\/properties\/Arthur%20(TM)\/works", "method": "GET", "parameters": null } ], "_embeds": null } ], "_links": [ { "rel": "https:\/\/api.penguinrandomhouse.com\/title\/domains\/definition", "href": "https:\/\/api.penguinrandomhouse.com\/title\/client\/Public\/domains\/PRH.US", "method": "GET", "parameters": null }, { "rel": "self", "href": "https:\/\/api.penguinrandomhouse.com\/title\/domains\/PRH.US\/properties?authorId=3496", "method": "GET", "parameters": null } ], "_embeds": null }, "error": null, "params": { "domain": "PRH.US", "clientGroup": "Public", "authorId": "3496" } }
/domains/PRH.US/works/219531/subseries
{ "status": "ok", "recordCount": 1, "startTimestamp": "2016-07-07T14:59Z", "endTimestamp": "2016-07-07T14:59Z", "timeTaken": 5, "data": { "subseries": [ { "subseries": "14 Days in Shonan", "_links": [ { "rel": "self", "href": "https:\/\/api.penguinrandomhouse.com\/title\/client\/Public\/domains\/PRH.US\/subseries\/14%20Days%20in%20Shonan", "method": "GET", "parameters": null }, { "rel": "https:\/\/api.penguinrandomhouse.com\/title\/authors\/definition", "href": "https:\/\/api.penguinrandomhouse.com\/title\/client\/Public\/domains\/PRH.US\/subseries\/14%20Days%20in%20Shonan\/authors", "method": "GET", "parameters": null }, { "rel": "https:\/\/api.penguinrandomhouse.com\/title\/titles\/definition", "href": "https:\/\/api.penguinrandomhouse.com\/title\/client\/Public\/domains\/PRH.US\/subseries\/14%20Days%20in%20Shonan\/titles", "method": "GET", "parameters": null }, { "rel": "https:\/\/api.penguinrandomhouse.com\/title\/works\/definition", "href": "https:\/\/api.penguinrandomhouse.com\/title\/client\/Public\/domains\/PRH.US\/subseries\/14%20Days%20in%20Shonan\/works", "method": "GET", "parameters": null } ], "_embeds": null } ], "_links": [ { "rel": "https:\/\/api.penguinrandomhouse.com\/title\/domains\/definition", "href": "https:\/\/api.penguinrandomhouse.com\/title\/client\/Public\/domains\/PRH.US", "method": "GET", "parameters": null }, { "rel": "self", "href": "https:\/\/api.penguinrandomhouse.com\/title\/domains\/PRH.US\/subseries?workId=219531", "method": "GET", "parameters": null } ], "_embeds": null }, "error": null, "params": { "domain": "PRH.US", "workId": "219531", "clientGroup": "Public" } }
Populating seoFriendlyUrl in search-display view
There was also a bug fixed where the seoFriendlyUrl element of the search-display view was not being populated.
/domains/PRH.US/search/views/search-display?q=green&docType=author
"id": "author-10955-PRH.US", "key": "10955", "name": "John Green", "docType": "author", "score": 5.8462825, "seoFriendlyUrl": "\/authors\/10955\/john-green", "authorId": "10955", "authorOf": { "workId": 536453, "isbn": 9781101984543, "title": "Textbook Amy Krouse Rosenthal", "hasCover": true, "seoFriendlyUrl": "\/books\/536453\/textbook-amy-krouse-rosenthal-by-textbook-amy-krouse-rosenthal" },
Bug
- [RHAPI-551] - AuthorOf URL not being set in search-display
New Feature
- [RHAPI-546] - Create /subseries and /property subresources