Feed the Book Duets API author and musician names. Receive a Markov chain mashup of their written and spoken words.
- User-Facing App
- What Are Book Duets?
- Get an API Key
- REST Endpoints
- Examples
- Formatting Artist Names
- History and Thanks
- License and Contributions
See this API in action by visiting www.bookduets.com!
Book Duets are computer-generated mashups of lyrics and literary quotes. Learn more about the connections between well-known musicians and authors.
Did you know that Haruki Murakami is a fan of Radiohead? Or that Chuck Palahniuk listened to Nine Inch Nails while writing Fight Club? Learn more trivia like this by requesting a randomly-generated Suggested Pairing Book Duet that highlights these intriguing connections and mashes up their work.
Or try your luck at creating a custom Book Duet by plugging in a musician and author of your choice. You might end up with something weird, thrilling, deep, or just plain nonsensical.
To use the Book Duets API, you'll need to register for an API key. (If you try to get Book Duets without an API key, then you'll get a 401 Unauthorized error.)
To register for a key:
POST "api.bookduets.com/register?email="[email protected]" You should receive a response that looks like this:
{"message":"Here is your unique API key.","api_key":"YOUR_SECRET_API_KEY"} Make sure to save this unique API key, since you will need it to retrieve Book Duets.
- Authentication - Once you have a unique API key, you'll need to send it in each request header for authentication, formatted as:
"Book-Duets-Key" => ENV['YOUR_SECRET_API_KEY'] Once your API key is in the request header, then you can hit the following endpoints.
-
Base URI:
api.bookduets.com -
GET a suggested pairing + a book duet:
/suggested_pairing?filter_level=FILTER_LEVEL -
GET a custom book duet:
/custom_duet?musician=MUSICIAN_NAME&author=AUTHOR_NAME&filter_level=FILTER_LEVEL
-
filter_level: This parameter is required for all lookups. Possible values include:
- none: No filtering - may contain offensive or explicit language
- med: Many curse words permitted, some offensive content is replaced with text bleeps (#@%!)
- hi: Both offensive language and curse words replaced by text bleeps (#@%!)
-
musician: Names (as they appear on Musixmatch)
-
author: Names (as they appear on WikiQuotes)
Here are some amazing examples of some past computer-generated mashups:
- /suggested_pairing?filter_level=hi
{"author": "Margaret Atwood", "musician": "Feist", "news_source": "http://flavorwire.com/384073/you-favorite-authors-favorite-musicians/4, "book_duet":"Gatekeeper, Gatekeeper seasons wait for your nod I feel it all. Oooh, I'll be the case now. Instead we are opposite, we touch as though attacking, the gifts we bring even in good faith maybe warp in our hands to implements, to maneuvers in restaurants we argue over which of..."}
- /custom_duet?musician=Hanson&author=Stephenie_Meyer&filter_level=hi
{"author": "Stephenie Meyer", "musician": "Hanson", "book_duet":"I'll give you passionate, I muttered. I truly knew - knew it deep in my eyes as I thrilled to the word."}
The following formatting options are supported by the Book Duets endpoints
- Spaces or Underscores (Crystal Castles, William_Gibson)
- Special characters (Anaïs Nin, Möterhead)
- Initials (S. E. Hinton or S._E._Hinton)
If you are having difficulty retrieving specific artists by name, check to see how they are formatted on Wikiquotes or Musixmatch. Book Duets relies on these APIs to build corpora for Markov dictionaries.
This was a part of my capstone project for Ada Developers Academy. As a music enthusiast and former freelance writer, I had quite a bit of fun blending my interests and putting this API together. I hope to expand on both the web app and the API in the future!
Mahalo to @jnf, @kariabancroft, and my cohort[2] unigoats for your invaluable instruction and support.
MIT License
Please feel free to submit suggestions or improvements via github to help make Book Duets even better!
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent