Story API changes for Books project

Contents
1 Overview
2 Changes to a Story element
2.1 New Parents
2.2 Book Edition
2.3 Cover Art for Books
2.4 Book List
3 New Aggregations
3.1 Lists of Mapping Codes
3.2 Metadata for Book and Author Aggregations
3.2.1 Authors in Book Aggregation Metadata and Vice Versa
3.2.2 Book "Traits"
4 Miscellaneous Changes
4.1 Fields Change
4.2 Required Fields Change
4.3
5 Looking Ahead to the Book or Entity API
Overview
The 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 parents
to 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 list here
is: 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 Parents
Books, 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 special
code 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 or
the 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.
<story id="131064823">
... cut irrelevant stuff...
<parent id="10101" type="book genre" slug="false">
<title>Biography & Memoir</title>
<link type="html">
http://www.npr.org/books/genres/10101/biography-memoir/
</link>
<link type="api">
http://api.npr.org/query?id=10101&apiKey=<key>
</link>
</parent>
<parent id="12344567" type="book" slug="false">
<title>Crazy Like Us</title>
<link type="html">

http://www.npr.org/books/titles/136854089/crazy-like-us-the-globalization-of-the-american-psyche
</link>
<link type="api">
http://api.npr.org/query?id=136854089&apiKey=<key>
</link>
</parent>
<parent id="2345678" type="author" slug="false">
<title>Ethan Watters</title>
<link type="html">
http://www.npr.org/books/authors/136854092/ethan-watters
</link>
<link type="api">
http://api.npr.org/query?id=136854092&apiKey=<key>
</link>
</parent>
... cut more irrelevant stuff...
</story>
Book Edition
We 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:
<bookEdition id="135941893">
<isbn>9780345351876</isbn>
<thingId>135941882</thingId>
<publisher>Random House</publisher>
<formatId>2</formatId>
<pubDate>1990-05-01 00:00:00</pubDate>
<pagination>252 p. ;</pagination>
<listPrice>6.99</listPrice>
</bookEdition>
In the API we would want this to be a little friendlier.
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 in
the API today:
<song id="136530787" audioId="136590427">
<title>Love Is The Drug</title>
<subtitle/>
<artist/>
<composer/>
<discNum>1</discNum>
<trackNum>4</trackNum>
<licensing/>
<publisher/>
<album>
<albumId>136530780</albumId>
<albumTitle>Black Sun</albumTitle>
<albumArtist>Kode9 & The Spaceape</albumArtist>
<albumYear>2011</albumYear>
<upc>5055300328434</upc>
<label>Hyperdub</label>
<labelNum/>
<promoUrl/>
<musicType>not specified</musicType>
<coverUrl>/assets/music/programs/asc/2011/05/kode9_cvr.jpg</coverUrl>
</album>
</song>
So we would add book level information inside the <bookEdition> tag in the same way. Books are modeled like other parent aggregations in the
API.
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:
<story id="131064823">
... cut irrelevant stuff...
<bookEdition id="135941893">
<isbn>9780345351876</isbn>
<book id="135941882">
<title>The Book Title</title>
<link type="html">
http://www.npr.org/books/titles/135941882/the-book-title
</link>
<link type="api">
http://api.npr.org/query?id=135941882&apiKey=<key>
</link>
</book>
<publisher>Random House</publisher>
<format>Paperback</format>
<pubDate>1990-05-01 00:00:00</pubDate>
<pagination>252 p. ;</pagination>
<listPrice>6.99</listPrice>
</bookEdition>
... cut more irrelevant stuff...
</story>
Cover Art for Books
Book 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 to
the story in the same container in which the book edition was added. Editors can replace the cover art image with any image they choose but
typically 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 promo
art to the API in general.
Note below for how cover art is handled in book lists.
Book List
The 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 API
What we call "list item" in seamus is called "member" in the API
There is no change at all to the way the <collection> element works in the API for books.
But the <member> element, while following the same general rules for all list types, would look a little different if only because the assets inside of
it 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 render
the collection. Furthermore, editors will be indicating which assets from the book should be displayed in the collection and the mobile platforms in
particular will want that information for recreating the collection.
Here is an example list item in a book list:
The <member> element would look like this:
<member id="132652688">
<promoArt refId="45467788" num="1"/>
<title num="2"><\!\[CDATA[Harry Patter And The Chamber Of Secrets]\]</title>
<author id="135941882" num="2">
<title>J. K. Rowling</title>
<link type="html">
http://www.npr.org/books/authors/135941882/j-k-rowlings
</link>
<link type="api">
http://api.npr.org/query?id=135941882&apiKey=<key>
</link>
</author>
<author id="1245678867" num="3">
<title>Mary GrandPre</title>
<link type="html">
http://www.npr.org/books/authors/1245678867/mary-grandpre
</link>
<link type="api">
http://api.npr.org/query?id=1245678867&apiKey=<key>
</link>
</author>
<edition refId="132652709" num="5"/>
<memberText num="6"><\!\[CDATA[When the Chamber of Secrets is opened again at the Hogwarts School
for
Witchcraft and Wizardry, second-year student Harry Potter finds himself in danger from
a
dark power that has once more been released on the school.
This is the description of the list item]\]</title>
<byline refId="23432455" num="7"/>
<link refId="4556453" num="8"/>
<link refId="4343456" num="9"/>
</member>
Note that the author tags are not references since as noted above the Best Seller lists will only include the author information in the list itself -
those stories will not have the book or author information in the parents elements.
The book edition, byline, and internal and external links will show up naturally as elements for the story in the same way all stories with lists. The
book information will be part of the book edition.
The promo art (the cover image) is a little tricky. The promo art is a child resource of the book edition, which is in turn the child resource of the list
item in Seamus. I'm not 100% sure these kinds of grandchildren assets are included in the API for stories currently because I can't think of
another example of one. However it will be needed in the API.
New Aggregations
We will have three new types of story aggregations:
One new aggregation is a book; if a user queries by a book ID, the API will return NPR stories that referenced the book.
Another new aggregation is an author; if a user queries by an author ID, the API will return NPR stories that referenced that author, which
will include stories that reference books the author wrote, stories that are interviews with the author, and stories for which the author
acted as a critic for a different book.
A third new aggregation will be book genre. When a book is associated with a story, the genres for that book are also associated with the
story. If a user queries by a genre ID the API will return NPR stories that reference books with that genre.
Lists of Mapping Codes
I am not planning on creating a list of "All Books" or "All Authors" since it would make more sense to me to wait until the entity API is developed.
But we should add a list of "All Book Genres" similar to the way we have lists of topics, blogs, series, etc. See
; http://www.npr.org/api/mappingCodes.php.&nbsp
Getting a list of music genres uses the ID 3018:
http://api.npr.org/lists?id=3018&apiKey=MDA0MTI1Nzg0MDEyNTQ3NzM1MjNhN2NjNA010
So I recommend we make book genres use the ID 3019.
Metadata for Book and Author Aggregations
If 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 metadata
for the "channel" or "list" element that it does for the <story> level element. Any resources such as book editions, images or inset text added to the
book 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 <book> element for authors and <author> elements for books in the
NPRML.
In the XmlStoryModel we pull these elements out separately so a book XmlStoryModel will have something like:
<author id="135941885">
<name>Anne McCaffrey</name>
</author>
and author would have a corresponding <book> tag:
<book id="135941882">
<title>Restoree</title>
</book>
In the API we would want to follow the API convention as we did above with the book element in the Book Edition resource
<book id="135941882">
<title>The Book Title</title>
<link type="html">
http://www.npr.org/books/titles/135941882/the-book-title
</link>
<link type="api">
http://api.npr.org/query?id=135941882&apiKey=<key>
</link>
</book>
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.
<list>
<title>John Steinbeck</title>
<teaser> NPR coverage of Murray John Steinbeck: News, author interviews, critics' picks and
more</teaser>
<miniTeaser>NPR coverage of Murray John Steinbeck: News, author interviews, critics' picks and
more</miniTeaser>
<link type="api">
http://api.npr.org/query?id=136809772&apiKey=MDAzMzQ2MjAyMDEyMzk4MTU1MDg3ZmM3MQ010
</link>
<link type="html">http://www.npr.org/books/authors/136809772/john-steinbeck</link>
<book id="135941882">
<title>East of Eden</title>
<link type="html">
http://www.npr.org/books/titles/135941882/east-of-eden
</link>
<link type="api">
http://api.npr.org/query?id=135941882&apiKey=<key>
</link>
</book>
<book id="135941882">
<title>Winter of Our Discontent</title>
<link type="html">
http://www.npr.org/books/titles/135942934/winter-of-our-discontent
</link>
<link type="api">
http://api.npr.org/query?id=135942934&apiKey=<key>
</link>
</book>
<story id="....">
</story>
<story id="....">
</story>
<story id="....">
</story>
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 Fiction
best 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:
<trait id="12345466" type="recommended">
<name> Recommended </name>
<value> true </value>
</trait>
<trait id="12345678" type="award">
<name>Pulitzer Prize</name>
<value>2010</value>
</trait>
<trait id="12334567" type="weeksonlist">
<name>Weeks on Best Seller Hardcover Fiction List</name>
<value>34</values>
</trait>
Miscellaneous Changes
Fields Change
It 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 have
been 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 Change
It is also likely that a user (particular a mobile app focused on books) might want to only have stories returned that include book editions. For
example 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 API
There 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 the
things 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 and
then 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.