library of congress, feb 21, 2018 @liblaura …...agenda 1. apis: definition and examples 2. loc.gov...
TRANSCRIPT
![Page 1: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/1.jpg)
Unboxing the Library:Introduction to APIs
Laura [email protected]
@liblaura
Library of Congress, Feb 21, 2018
![Page 2: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/2.jpg)
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
![Page 3: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/3.jpg)
API = Application
Programming Interface
![Page 4: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/4.jpg)
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!)
![Page 5: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/5.jpg)
What do you use an API for?
![Page 6: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/6.jpg)
Getting data in real-time
![Page 7: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/7.jpg)
![Page 8: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/8.jpg)
![Page 9: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/9.jpg)
"I am It, and It is I": Lovecraft in Providence
![Page 10: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/10.jpg)
Using APIs to getdata for analysis
![Page 11: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/11.jpg)
![Page 12: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/12.jpg)
![Page 13: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/13.jpg)
![Page 14: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/14.jpg)
![Page 15: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/15.jpg)
Uses for an API● Embed data in a website in real-time● Get data for analysis● Communication between software
components● More...
![Page 16: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/16.jpg)
That still seems abstract to me...
![Page 17: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/17.jpg)
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.
![Page 18: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/18.jpg)
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
![Page 19: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/19.jpg)
"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/
![Page 20: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/20.jpg)
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
![Page 21: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/21.jpg)
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
![Page 22: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/22.jpg)
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
![Page 23: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/23.jpg)
Documentation / Reference Guide for loc.gov JSON API
![Page 24: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/24.jpg)
Making an API request https://www.hurl.it
Website for constructing API calls and basic exploration.
Demo then hands-on
![Page 26: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/26.jpg)
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
![Page 27: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/27.jpg)
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!
![Page 28: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/28.jpg)
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
![Page 29: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/29.jpg)
![Page 30: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/30.jpg)
![Page 32: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/32.jpg)
![Page 33: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/33.jpg)
![Page 34: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/34.jpg)
Photo Roulette
![Page 35: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/35.jpg)
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.
![Page 36: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/36.jpg)
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.
![Page 37: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/37.jpg)
![Page 38: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/38.jpg)
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.
![Page 39: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/39.jpg)
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.
![Page 40: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/40.jpg)
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.
![Page 41: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/41.jpg)
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.
![Page 42: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/42.jpg)
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.
![Page 43: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/43.jpg)
What next?
![Page 44: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/44.jpg)
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.
![Page 45: Library of Congress, Feb 21, 2018 @liblaura …...Agenda 1. APIs: definition and examples 2. loc.gov JSON API in-depth 3. Hands-on 4. Examples of code using APIs 5. APIs: promise and](https://reader035.vdocuments.site/reader035/viewer/2022062918/5ede5be9ad6a402d6669ae77/html5/thumbnails/45.jpg)
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.