TECH StoryAPIchangesforBooksproject 260911 1155 55

8/12/2019 TECH StoryAPIchangesforBooksproject 260911 1155 55

1/8

Story API changes for Books project

Contents

1 Overview2 Changes to a Story element

2.1 New Parents2.2 Book Edition2.3 Cover Art for Books2.4 Book List

3 New Aggregations3.1 Lists of Mapping Codes3.2 Metadata for Book and Author Aggregations

3.2.1 Authors in Book Aggregation Metadata and Vice Versa3.2.2 Book "Traits"

4 Miscellaneous Changes4.1 Fields Change4.2 Required Fields Change4.3

5 Looking Ahead to the Book or Entity API

OverviewThe changes to the Story API for the books project are not large.

There will be a few new types of aggregations of stories: stories associated with books, authors and book genres. These will show up as parentsto stories.

There is a new resource type - the Book Edition These will show up in story entity XML like any other resource such as audio, video, images,etc.

There has been one new list type added to Seamus in the Book project so far. It is described . It will be included in the API as any other listhereis: see for the documentation on lists in the API.here

Users of the API can get metadata level information about the new aggregations using the &meta=inherit parameter currently used in the API.This would include author and book data plus book traits like awards won or NPR recommended.

We will want to add book edition as one of the resources that can be used in the fields and required fields parameters in the API.

Changes to a Story element

New ParentsBooks, Authors and Book Genres can be parents to story pages but they work like any other parent so there is no need to create a lot of specialcode for them. We just need to add new types.

Keep in mind that not every story that has a book edition will have a parent that is the book. Best Seller lists in particular will not have the book orthe author as a parent so they will not show up on lists of stories associated with the book or author and overwhelm the results for a popular book.

That said, here's an example of what these new parents would look like in a story element.
http://confluence.npr.org/display/TECH/Proposal+for+a+Simple+Book+List+for+the+Ida+releasehttp://confluence.npr.org/display/TECH/API+-+Lists+Designhttp://confluence.npr.org/display/TECH/API+-+Lists+Designhttp://confluence.npr.org/display/TECH/Proposal+for+a+Simple+Book+List+for+the+Ida+release


2/8

... cut irrelevant stuff...

Biography & Memoir http://www.npr.org/books/genres/10101/biography-memoir/ http://api.npr.org/query?id=10101&apiKey= Crazy Like Us http://www.npr.org/books/titles/136854089/crazy-like-us-the-globalization-of-the-american-psyche http://api.npr.org/query?id=136854089&apiKey= Ethan Watters

http://www.npr.org/books/authors/136854092/ethan-watters http://api.npr.org/query?id=136854092&apiKey= ... cut more irrelevant stuff...

Book EditionWe need to add the Book Edition resource to elements that can show up in NPRML.

A book edition resource looks like this in the XmlStoryModel:

9780345351876 135941882 Random House 2 1990-05-01 00:00:00 252 p. ; 6.99

In the API we would want this to be a little f riendlier.

We should link to the book in a similar way that we link to album inside a song element in the API now. Here is an example of a song element inthe API today:


3/8

Love Is The Drug 1 4 136530780 Black Sun Kode9 & The Spaceape 2011 5055300328434 Hyperdub not specified /assets/music/programs/asc/2011/05/kode9_cvr.jpg

So we would add book level information inside the tag in the same way. Books are modeled like other parent aggregations in theAPI.

In addition, we'll probably want the format of the edition to be something meaningful rather than just a code.

So here is what a book edition resource would look like in a story element:

... cut irrelevant stuff... 9780345351876 The Book Title http://www.npr.org/books/titles/135941882/the-book-title http://api.npr.org/query?id=135941882&apiKey= Random House Paperback 1990-05-01 00:00:00 252 p. ; 6.99 ... cut more irrelevant stuff...

Cover Art for BooksBook Editions resources can have promo art resources associated with them to represent the cover art for the edition.

In Seamus, when a book edition is added to a story as an asset, the promo art resource associated with the book is also added automatically tothe story in the same container in which the book edition was added. Editors can replace the cover art image with any image they choose buttypically a story about a single book will use the cover art as its primary image.

Nothing special needs to be done in the API for including these images in the story API except that we have an outstanding ticket to add promoart to the API in general.

Note below for how cover art is handled in book lists.


4/8

Book ListThe book list follows the same list design as the music playlists and the simple list, described . here

Just a reminder about terminology:

What we call "list" in seamus is called "collection" in the APIWhat we call "list item" in seamus is called "member" in the API

There is no change at all to the way the element works in the API for books.

But the element, while following the same general rules for all list types, would look a little different if only because the assets inside ofit are different. We want to ensure that API end users looking at book lists don't have to do multiple additional API queries per item just to renderthe collection. Furthermore, editors will be indicating which assets from the book should be displayed in the collection and the mobile platforms inparticular will want that information for recreating the collection.

Here is an example list item in a book list:

The element would look like this:
http://confluence.npr.org/display/TECH/API+-+Lists+Designhttp://confluence.npr.org/display/TECH/API+-+Lists+Design


5/8


6/8

Metadata for Book and Author AggregationsIf a user queries the story API and uses a book or author ID, then the list of stories returned will be stories which are linked to that book or author.This is no different than any other type of query in the story API.

End users can use the &meta=inherit to get book level or author level metadata however. This flag causes the API to display the same metadatafor the "channel" or "list" element that it does for the level element. Any resources such as book editions, images or inset text added to thebook landing page or the author landing page would be included. Again, this is no different than for any other type of aggregation.

The following are special metadata for books and authors only.

Authors in Book Aggregation Metadata and Vice Versa

When the &meta=inherit flag was passed to the API, we would need to add a element for authors and elements for books in theNPRML.

In the XmlStoryModel we pull these elements out separately so a book XmlStoryModel will have something like:

Anne McCaffrey

and author would have a corresponding tag:

Restoree

In the API we would want to follow the API convention as we did above with the book element in the Book Edition resource

The Book Title http://www.npr.org/books/titles/135941882/the-book-title http://api.npr.org/query?id=135941882&apiKey=

and do a similar thing with the author.

So if I were to query an author, I might see something like this if I pass in the &meta=inherit parameter.


7/8

John Steinbeck NPR coverage of Murray John Steinbeck: News, author interviews, critics' picks andmore NPR coverage of Murray John Steinbeck: News, author interviews, critics' picks andmore http://api.npr.org/query?id=136809772&apiKey=MDAzMzQ2MjAyMDEyMzk4MTU1MDg3ZmM3MQ010 http://www.npr.org/books/authors/136809772/john-steinbeck East of Eden http://www.npr.org/books/titles/135941882/east-of-eden http://api.npr.org/query?id=135941882&apiKey= Winter of Our Discontent http://www.npr.org/books/titles/135942934/winter-of-our-discontent

http://api.npr.org/query?id=135942934&apiKey=

Book "Traits"

There is a new resource type we developed for books that will be reusable in other applications in NPR.org as time goes on. This is the"TraitResource" where editors assign such traits to books as "Recommended by NPR" or "Pulitzer Prize Winner 2010" or "On Hardcover Fictionbest seller list for 34 weeks".

NOTE: Book traits are included in API output ONLY when:

1. The API Call is for the BOOK LANDING PAGE story (NOT for Book Story Pages or Lists).

2. The meta=inherit query parameter is used in the API Call.

The API data for the traits listed above will look like this:

Recommended true

Pulitzer Prize 2010 Weeks on Best Seller Hardcover Fiction List 34

Miscellaneous Changes


8/8

Fields ChangeIt is likely that book edition will be one of the fields that a user might want to select. A user for example might just want a list of books that havebeen discussed on Books We Like recently. They could use :

http://api.npr.org/query?id=91752774&fields=bookedition&apiKey=MDAzMzQ2MjAyMDEyMzk4MTU1MDg3ZmM3MQ010&live=1

This should return a list of stories on that series with the book edition(s) discussed on each one.

Required Fields ChangeIt is also likely that a user (particular a mobile app focused on books) might want to only have stories returned that include book editions. Forexample we could get a list of Fresh Air stories about books by using:

http://api.npr.org/query?id=13&requiredAssets=bookedition&apiKey=MDAzMzQ2MjAyMDEyMzk4MTU1MDg3ZmM3MQ010&live=1

This is more work however - this means we need to update the API database so the Story table contains a column storyBookEditionTotal.

This column should be set to zero for all past stories but we need to make sure this gets updated in the Book story migration.

Looking Ahead to the Book or Entity APIThere is some functionality desired by the books team that can not be done using the story API. Here's an incomplete list to indicate some of thethings that the story API can not do:

We can not get a sortable, page-able list of books for a genre or a series. We can only retrieve a list of stories for a genre or series andthen derive a list of books from that story list.We can not get a list of recommended books.We can not get a list of books which have won awards.
http://api.npr.org/query?id=91752774&fields=bookedition&apiKey=MDAzMzQ2MjAyMDEyMzk4MTU1MDg3ZmM3MQ010&live=1http://api.npr.org/query?id=13&requiredAssets=bookedition&apiKey=MDAzMzQ2MjAyMDEyMzk4MTU1MDg3ZmM3MQ010&live=1http://api.npr.org/query?id=13&requiredAssets=bookedition&apiKey=MDAzMzQ2MjAyMDEyMzk4MTU1MDg3ZmM3MQ010&live=1http://api.npr.org/query?id=91752774&fields=bookedition&apiKey=MDAzMzQ2MjAyMDEyMzk4MTU1MDg3ZmM3MQ010&live=1

Documents

TECH StoryAPIchangesforBooksproject 260911 1155 55