API Hackery:Customizing Your Library’s

Services Using APIs

Nicholas SchillerWSU Vancouver LibraryOnline Northwest 2013

February 8, 2013Corvallis, OR

Presentation site: bit.ly/XqyzfMTest the app: bit.ly/WvqAR4Code on GitHub: https://github.com/nnschiller/easy_api

Desired Outcomes:

You will be able to explain how APIs work.

You’ll leave with ideas on how APIs can help your patrons.

You’ll leave energized to make things.

This Talk is Not:

A step-by-step tutorial or walkthrough. (There will be gaps.)

A coding lesson. (My role there is student or peer not instructor.)

A technical treatment of the subject.

Application Programming Interfaces

Specifications and standards

Keys to the silo

How to ask a service for what you want.

APIs are:

APIs are about sharing data.

Librarians are about sharing information.

APIs and Librarians should be friends.

APIs are a key part of library systems’

movement from closed “black-box” tools to truly open systems.

Examples:Google Maps API

With an authentication key and latitude & longitude coordinates, you can put a map on your page.

WorldCat Search API

Twitter APIs

Instructions for capturing tweets and hashtags.

Our Beatrice

We’ll want a guide to lead us through this.For technology optimists: he will be our Beatrice.

For technology pessimistshe will be our Virgil.

Dr. Walter Bishop

Our guide for building wonderful things with APIs

I am forming a hypothesis.

Would you

like to hear it?

2/3

1/6

1/6

the problem & solution the code the design

The relative difficulty* of making library

tools with APIs.

The Relative Difficulty Levels*

2/3

1/6

1/6

the problem & solution the code the design

*Two caveats:

1. I made these ratios up. They don’t reflect my time invested.

2. What we don’t know howto do (yet) seems much harder, but we can learn & we can find help.

“Pseudo-code is your friend” or follow Anne Lamott’s advice on first drafts.

Articulate your problem and identify a solution.

+Write code

using an API to generate the

desired solution.

+Wrap the

solution code in a user

friendly format.

Articulate Information Need, form

Boolean Queries, ID Appropriate Data Sources

+API + scripting language (PHP,

JavaScript, Ruby, Python) + HTML 5

+HTML 5, CSS 3 & jQuery Mobile

“Let me introduce you to test subject #6.”

Practical example of an API solving a real library problem.

Our WorldCat Local discovery layer presents obstacles to students who are looking for ebooks.

The ebooks facet doesn’t use the same definition of ebook that our students assume.

“We need her to help us understand this skill.”

To Successfully find an eBook in our collection:

Type the following into our WorldCat discovery tool:

kw:NASA +mt:ebk -mt:gnp -mt:cpb -mt:deg

Also consider excluding material typesupw, upc, cdc, dct

Don't you understand this is Greek to me? Except that I speak

Greek. This is Aramaic to me. Not the western dialect, I do speak it.

What we need is:

something to automatically do this for eBook searches.

to get the user’s search query, add our Boolean logic phrase to the query, get the results and present them to the user.

the WorldCat Search API.

While we’re at it

Let’s format our tool for tablets and mobile devices.

Let’s connect the user directly to the full text right on their tablets and/or mobile devices or whatever screen they prefer.

(I’m working on the assumption that eBooks and tablets go together.)

Core Librarian skills: information need articulation, Boolean queries,

data source expertise

+API + scripting language (PHP,

JavaScript, Ruby) + HTML 5

+HTML 5, CSS 3 & jQuery Mobile

WorldCat Search API

Request a key. (Keys denote permission to access the service.)

Submit your requests formatted in either opensearch or SRU standards.

Specify how you want the data returned.

WorldCat Search API

Opensearch: from A9 www.opensearch.org

basic structure, kw indexes only

returns RSS or Atom

SRU: www.loc.gov/standards/sru/

enables complex queries of multiple indexes

returns XML or MARC

For Our Examplewe can use both

The WorldCat Search API can return formatted citations using opensearch.

Opensearch only searches keyword indexes but our search requires the material type index.

If we want to search the mt: index and get formatted citations, we’ll need to use opensearch with SRU formatting. The API allows this.

http://www.worldcat.org/webservices/catalog/search/worldcat/opensearch?q=srw.kw+any+%22biofuel%22+and

+srw.li+any+%22ws2%22+and+srw.mt+any+%22ebk%22+not+srw.mt+any+

%22gpb%22+not+srw.mt+any+%22cnp%22+not+srw.mt+any+%22deg

%22&format=rss&cformat=chicago&wskey=[insert your API key here]

A friend from Washington State invented these glasses in order to

be able to see a URL’s aura.

http://www.worldcat.org/webservices/catalog/search/

worldcat/opensearch?q=srw.kw+any+”biofuel”+and+srw.li+any+”ws2”

+and+srw.mt+any+”ebk”+not+srw.mt+any+”gpb”+not+srw.mt+any

+”cnp”+not+srw.mt+any+”deg”&format=rss&cformat=chicago

&wskey=[insert your API key here]

Let’s Celebrate, Becausethe Hard Part is Done.

API + scripting language (PHP) +

HTML 5

Excellent. Let’s make some <?PHP ?>

Do You Remember?

Slide 17: “What we need is to get the user’s search query, add our Boolean logic phrase to the query, get the results and present them to the user.”

Our code will do EXACTLY these three things.

As a n00b coder, I was only able to succeed by keeping a razor-sharp focus on exactly these goals.

Audience Choice:

Look at the code

Look at the web app (beta)

Special Thanks to:

Jason Clark with Montana State University Libraries

Bruce Washburn with OCLC Research

They shared their code under FreeBSD and GNU open licenses, allowing me to borrow freely.

HTML 5, CSS 3 &

jQuery Mobile

Either a green unicorn just raced across the lab,

or I accidentally used jQuery Mobile.

jQuery Mobile automates:

The buttons, pickers, & search inputs

The theme and color scheme

The behavior in diverse screens and browsers

John Noble / Walter Bishop / Walternate images are from the Fox TV series Fringe and are used under fair use as set forth in the Code of Best Practices for Fair Use in Online Video. See especially #6 SIX: Quoting in Order to Recombine Elements to Make a New Work That Depends for its Meaning on (Often Unlikely) Relationships Between the Elements.

The images from Dore’s engravings of Dante’s Divine Comedy are in the public domain.

Image Credits

Demo the Web App (beta)bit.ly/WvqAR4

Code Repository on GitHub: https://github.com/nnschiller/

easy_api

Further ReadingOCLC Worldcat Search API

http://www.oclc.org/developer/services/worldcat-search-api

http://www.oclc.org/worldcatapi/default.htm

http://www.oclc.org/us/en/support/documentation/firstsearch/z3950/z3950_databases/specs/materialtypes.htm

http://www.oclc.org/developer/news/worldcat-search-api-tips-and-tricks

Opensearch

http://www.opensearch.org/Home

http://oclc.org/developer/documentation/worldcat-search-api/opensearch-responses

SRU

http://www.loc.gov/standards/sru/

http://www.worldcat.org/webservices/catalog/search/sru?wskey=[YOUR WCS API KEY IS REQUIRED]

Further Reading

Tutorials

http://www.codecademy.com/courses/javascript-beginner-en-EID4t

http://www.tizag.com/phpT/

http://www.codecademy.com

Code

http://www.worldcat.org/devnet/code/devnetDemos/trunk/webservices_php_libraries/wcapi_opensearch.php

http://www.lib.montana.edu/~jason/files/worldcat-basic/code.txt

Further Reading

API Hackery:Customizing Your Library’s

Services Using APIs

Nicholas SchillerWSU Vancouver LibraryOnline Northwest 2013

February 8, 2013Corvallis, OR

Presentation site: bit.ly/XqyzfMTest the app: bit.ly/WvqAR4Code on GitHub: https://github.com/nnschiller/easy_api