- Previous: Multiple authors
- Up: Concepts
- Next: Series numbers
Contributor role
When associating people with books, the term "author" is a natural fit which is why we call our people resource /authors. But in truth we could have used the term "contributor" because people contribute to books in many ways besides simply authoring the content such as illustrating, narrating, or editing. This API models the type of contribution that a person made to a book with a role code.
Contributor role codes
Every ISBN has up to five people mapped to it and each mapping is qualified with a contributor role code that identifies the type of contribution that person made to the ISBN. Unfortunately for books where there are more than five contributors, we cannot capture those relationships with specific IDs although some of those people may be mentioned in the author display fields.
Contributor role codes are selected from a table of 41 entries.
+-----------------+---------------------------+-----+ | contribrolecode | contribroledesc | seq | +-----------------+---------------------------+-----+ | A | Author | 10 | | I | Illustrator | 20 | | 4 | Read by | 30 | | U | Foreword by | 40 | | V | Introduction by | 50 | | 1 | Preface by | 60 | | E | Editor | 70 | | D | Afterword by | 80 | | Q | Epilogue by | 90 | | P | Photographer | 100 | | T | Translator | 110 | | L | Compiled by | 120 | | O | Designed by | 130 | | 0 | Text by (art/photo books) | 999 | | 2 | Prologue by | 999 | | 3 | Produced by | 999 | | 5 | Retold by | 999 | | 6 | Revised by | 999 | | 7 | Selected by | 999 | | 8 | Series Editor | 999 | | 9 | Supplement by | 999 | | A1 | Appendix by | 999 | | A2 | Arranged by (music) | 999 | | A3 | Conductor | 999 | | A4 | Dramatized by | 999 | | A5 | Lyrics by | 999 | | A6 | Maps by | 999 | | B | Abridged by | 999 | | C | Adapted by | 999 | | F | Annotations by | 999 | | G | As told to | 999 | | H | As told by | 999 | | J | Contribution by | 999 | | K | Commentaries by | 999 | | M | Created by | 999 | | N | Concept by | 999 | | R | Experiments by | 999 | | S | Footnotes by | 999 | | W | Memoir by | 999 | | Y | Narrated by | 999 | | Z | Notes by | 999 | +-----------------+---------------------------+-----+
As you can see there is a sequence value that is used to prioritize certain roles over others. This sequencing is used when ordering contributors within a work or title.
This list can be retrieved from the API with the /roles endpoint.
/domains/PRH.US/roles
{
"status":"ok",
"recordCount":41,
"startTimestamp":"2015-11-20T08:27Z",
"endTimestamp":"2015-11-20T08:27Z",
"timeTaken":4,
"data":{
"roles":[
{
"code":"A",
"description":"Author",
"_embeds":null,
"_links":[
]
},
{
"code":"I",
"description":"Illustrator",
"_embeds":null,
"_links":[
]
},
{
"code":"4",
"description":"Read by",
"_embeds":null,
"_links":[
]
},
Getting role codes in the response
If you fetch an author without any context, then the "contribRoleCode" and "contribRoleDesc" elements are left empty.
/domains/PRH.US/authors/25754
"authorId":25754,
"display":"Nora Roberts",
"first":"Nora",
"last":"Roberts",
"company":{
"key":"R_H",
"value":null
},
"clientSourceId":0,
"seoFriendlyUrl":"/authors/25754/nora-roberts",
"contribRoleCode":null,
"contribRoleDesc":null,
That makes sense because a person only has a contributor role with respect to a particular title or work.
If instead, we list the authors in the context of a particular work or ISBN, then we see that those elements are populated.
/domains/PRH.US/works/317918/authors
"authorId":25754,
"display":"Nora Roberts",
"first":"Nora",
"last":"Roberts",
"company":{
"key":"R_H",
"value":null
},
"clientSourceId":0,
"seoFriendlyUrl":"/authors/25754/nora-roberts",
"contribRoleCode":"A",
"contribRoleDesc":"Author",
Filtering by role code
Restricting contributor lists
You can specify a "contribRoleCode" parameter to restrict results based on this contribution type. A simple example would be to list all of the people who have Photographer contributions in the "PRH.US" domain.
/domains/PRH.US/authors?contribRoleCode=P
{
"status":"ok",
"recordCount":434,
"startTimestamp":"2015-11-20T07:40Z",
"endTimestamp":"2015-11-20T07:40Z",
"timeTaken":1950,
"data":{
"authors":[
{
"authorId":278,
"display":"Arlene Alda",
"first":"Arlene",
"last":"Alda",
So we can see that there are 434 different people in the API who have Photographer contributions.
Restricting title or work lists
Another way to use the role code would be to filter the type of titles or works that are returned when listing them for a particular author. For example Maya Angelou is author ID #676. We can list her works in the usual way like this:
/domains/PRH.US/authors/676/works
{
"status":"ok",
"recordCount":35,
"startTimestamp":"2015-11-20T08:19Z",
"endTimestamp":"2015-11-20T08:19Z",
"timeTaken":11,
"data":{
"works":[
{
"workId":3909,
"title":"All God's Children Need Traveling Shoes",
"author":"Maya Angelou",
"onsale":"1991-06-04",
But if we only wanted to see books that she has a "Reader" contribution for, we could add a "contribRoleCode" filter.
/domains/PRH.US/authors/676/works?contribRoleCode=4
{
"status":"ok",
"recordCount":11,
"startTimestamp":"2015-11-20T08:16Z",
"endTimestamp":"2015-11-20T08:16Z",
"timeTaken":9,
"data":{
"works":[
{
"workId":3911,
"title":"Amazing Peace",
"author":"Maya Angelou",
"onsale":"2005-12-01",
Omitting specific roles
If instead we wanted to list works but omit any where she had written a foreword or introduction, we could use the "ignoreContribRole" parameter.
/domains/PRH.US/authors/676/works?ignoreContribRole=U&ignoreContribRole=V
{
"status":"ok",
"recordCount":33,
"startTimestamp":"2015-11-20T08:18Z",
"endTimestamp":"2015-11-20T08:18Z",
"timeTaken":7,
"data":{
"works":[
{
"workId":3909,
"title":"All God's Children Need Traveling Shoes",
"author":"Maya Angelou",
"onsale":"1991-06-04",
If we compare this result to the one above that did not restrict her works, we can see that this request returned 33 results whereas the full list was 35. This request therefore removed the single title for which she wrote the foreword and another for which she wrote the introduction.
Contributors with multiple roles
Christopher Plummer at Upstatement asked a very good question: can an author be related to the same ISBN with more than one role? The answer is yes. Here we can see that for The Twelve Days of Christmas, Jan Brett is both the author and the illustrator.
/domains/PRH.US/titles/9780399243295/authors
"authors":[
{
"authorId":3201,
"display":"Jan Brett",
"first":"Jan",
"last":"Brett",
"company":{
"key":"R_H",
"value":null
},
"clientSourceId":0,
"seoFriendlyUrl":"/authors/3201/jan-brett",
"contribRoleCode":"A",
"contribRoleDesc":"Author",
"_links":[
],
"_embeds":null
},
{
"authorId":3201,
"display":"Jan Brett",
"first":"Jan",
"last":"Brett",
"company":{
"key":"R_H",
"value":null
},
"clientSourceId":0,
"seoFriendlyUrl":"/authors/3201/jan-brett",
"contribRoleCode":"I",
"contribRoleDesc":"Illustrator",
"_links":[
],
"_embeds":null
}
],
Another common example of this would be an author who reads their own audio book.
- Previous: Multiple authors
- Up: Concepts
- Next: Series numbers
0 Comments
Please sign in to post a comment.