library of congress, feb 21, 2018 @liblaura …...agenda 1. apis: definition and examples 2. loc.gov...
TRANSCRIPT
Unboxing the Library:Introduction to APIs
Laura [email protected]
@liblaura
Library of Congress, Feb 21, 2018
Agenda1. APIs: definition and examples2. loc.gov JSON API in-depth3. Hands-on4. Examples of code using APIs5. APIs: promise and the reality6. Supporting API users7. Next steps for learning more
API = Application
Programming Interface
But really, what’s an API? ● A web server--at a URL--that an application or
program can query for data.● Some APIs can be receive data updates, too. ● Syntax for making requests for data.● Responses are structured data.● Response is formatted for computers
(although humans can read it too!)
What do you use an API for?
Getting data in real-time
"I am It, and It is I": Lovecraft in Providence
Using APIs to getdata for analysis
Uses for an API● Embed data in a website in real-time● Get data for analysis● Communication between software
components● More...
That still seems abstract to me...
loc.gov JSON API in depth The Library of Congress website (https://www.loc.gov) is also an API.
For any web page, you can get JSON format rather than HTML.
JSON: JavaScript Object Notation { key: value, key: value, … }
Keys are strings: “name”, “url”, “subject”
Values may be:
● string
● number
● boolean: true or false
● another JSON object
● an array [ ] of values
● null
"title": "Cat and kittens / after Henrietta Ronner.","medium": [
"1 print : chromolithograph ; sheet 31.6x 22.3 cm."],
"notes": ["Title from item.","From series: Fac-similes of Water Color Drawings and Oil Paintings by eminent artists, published by W. Schaus, 749 Broadway, N.Y.",
],"marc":
"//www.loc.gov/pictures/item/2017650796/marc/","digitized": true,
https://www.loc.gov/item/2017650796/
Making an API request: Terminology REST APIs: Use the web like your browser does, makes HTTP requests.
HTTP: protocol for sending requests and responses on the web. Parts of a request:
● URL● Method (GET, POST)● List of Headers ● Body
Anatomy of an API request
https://www.loc.gov/search/?q=dogs&fo=json
base URL (endpoint) parameters
https://www.loc.gov/collections/civil-war-maps/?fa=location:tennessee&fo=json
base URL parameters
Quick view of loc.gov JSON Add fo=json parameter to URL query string (the part after ?)
https://www.loc.gov/item/2017650796/?fo=json
Documentation / Reference Guide for loc.gov JSON API
Making an API request https://www.hurl.it
Website for constructing API calls and basic exploration.
Demo then hands-on
Making API Requests using Hurlhttps://www.hurl.it
Destination: [GET] https://www.loc.gov/search/
Authentication: ignore (no API key required)
Headers: ignore
Parameters: fo jsonq kittensat results,pagination
Make some more requestsDocumentation (see requests, responses):https://libraryofcongress.github.io/data-exploration
Not sure what to search on? 1. Browse the loc.gov site by collection, select some
facets, use that search URL as the Destination URL .2. Add the parameter: q json3. Add another parameter, based on what you see in the
documentation. Try “at” to limit the fields. 4. Launch request!
Using code to query APIs1. Custom dataset from loc.gov joined with other
data.
2. LC for Robots: Jupyter notebooks using Python
3. Library of Congress Colors: Python
4. Photo Roulette: JavaScript
Photo Roulette
Library APIs: the promise● Users can create datasets with just what
they need.
● Complement to bulk data downloads.
● Open up creative uses of collections data.
● Become more than a portal: be open to
conversations with users.
Library APIs: the reality ● Can be a high bar to use them.
● Require access to software tools,
knowledge of how to use with code.
● Metadata fields can seem opaque, data
structure unclear.
● Transforming data into another format
usually still required.
Beginner-level technical expertise:● Step-by-step tutorials that don’t require coding.
● Accompany parameters and field descriptions
with relevant examples.
● Provide an API console.
● Training opportunities for in-house staff so they
can support users.
● Provide ready-made code snippets for the most
general use cases.
Wuyts, Jolan. Cultivating APIs in the cultural heritage sector: Lessons from an internship at Europeana. Jan. 2018.
High-level technical expertise:● Make documentation pages searchable.
● Provide info about error codes, responses, and
debugging info.
● Answer advanced questions and issues in a
technical FAQ.
● Make it possible for users to help each other and
discuss the use of the API in a public online
discussion forum.
Wuyts, Jolan. Cultivating APIs in the cultural heritage sector: Lessons from an internship at Europeana. Jan. 2018.
Researchers:● Provide downloadable datasets in addition to
APIs.
● Publish a statistical analysis of the library’s
data, to show preliminary results about the
contents of the repository/collection.
● Highlight researchers’ publications and
projects which use library content from APIs
or datasets.
Wuyts, Jolan. Cultivating APIs in the cultural heritage sector: Lessons from an internship at Europeana. Jan. 2018.
Creative users:● Organise group events to encourage reuse.
● Encourage user feedback.
● Track impact of the API through what users have
created with your platform.
● Provide clear rights statements so creative users
know if and how they can reuse your data.
Wuyts, Jolan. Cultivating APIs in the cultural heritage sector: Lessons from an internship at Europeana. Jan. 2018.
People writing code:● Show how internal applications built on the API
are created and link to code.
● Provide code libraries so people can use the API
with the programming language they prefer.
● Clearly state terms of use or licenses that affect
commercial use of the API or content.
● Provide version history for the API.
● Library could archive and/or host projects.
Wuyts, Jolan. Cultivating APIs in the cultural heritage sector: Lessons from an internship at Europeana. Jan. 2018.
What next?
Keep learning!● Explore the documentation / reference guide.● Use Hurl to make more API requests. Add a browser
JSON extension to view pages using fo=json.● Look at how metadata appears in API responses.● Try other APIs. Request keys and practice:
○ DPLA’s API○ Data.gov
● Install Anaconda and download Jupyter notebooks. ● Pair up! Work with someone outside your team.
Credits and resourcesWorkshop handout.DC Public Library Catalog. (Accessed Feb. 18, 2018.)
“Reviews by Wirecutter: The Best French Press.” Wirecutter.com, Oct. 15, 2017.
Mawyer, Paul. "I am It, and It is I": Lovecraft in Providence.
Keller, Chris and Priya Krishnakumar. "The Comey firing has people concerned. Here’s where U.S. senators stand." LA Times. May 11, 2017.
ProPublica Congress API, 2018.
Bajak, Aleszu. “How to use ProPublica’s API.” StoryBench. May 15, 2017.
Schaus, W. , Publisher, W Schaus, and Henriette Ronner. Cat and kittens / after Henrietta Ronner. , 1867. [New York: Published by W.
Schaus, 749 Broadway, N.Y] Photograph. Retrieved from the Library of Congress. (Accessed Feb. 21, 2018.)
Library of Congress. loc.gov JSON API documentation. 2018.
Wrubel, Laura. Library of Congress Colors. 2018.
Wrubel, Laura. LOC Photo Roulette. 2018.
Averkamp, Shawn. “Computation in Conversation: Fostering New Fluencies in Collections as Data.” NDSR Guest Presentation, Library of
Congress, Nov. 13, 2017.
Wuyts, Jolan. Cultivating APIs in the cultural heritage sector: Lessons from an internship at Europeana. Jan. 2018.
