What makes a good API for a library? Or more importantly, what makes it bad?

Implementing an API is an art. It’s the connection between the user and the library itself. How can we optimize that connection to make the experience more pleasing? What makes a user reach for one library over another? What goes into an ergonomic API?

This talk will first discuss what makes an API good: documentation, simplicity, consistency, completeness, and flexibility. We will apply those elements by looking at examples in the wild of good and poorly designed APIs.

Credits & Resources

Images & Icons

• Background image (slide #1, #106)
• Breville plug from Amazon (slide #3)
• Stylized cover of The Design of Everyday Things from this Medium post (slide #4)
• Opening Quote icon by Xinh Studio from NounProject.com (slides #5, #6, & #105)
• Thought Bubble (filled) by alerma from NounProject.com (slides #15-18)
• Thought Bubble (lined) by alerma from NounProject.com (slides #16-18)
• Python package image from this Medium post (slides #19 & #21)
• Coffee pot “for masochists” image (slide #21)
• Cassette by Maxim Kulikov from NounProject.com (slide #22)
• Car by Simon Child from NounProject.com (slide #25)
• Ribbon by Karla Design from NounProject.com (slides #26-32, #34-47, #50-74, #77-94, #100-103)
• VHS Tape by Likous from NounProject.com (slide #99)

Fonts

• Neon 80s
• VCR OSD Mono
• Futura

Further Reading

• The Design of Everyday Things wiki, Amazon - Don Norman
• A Brief, Opinionated History of the API - talk by Joshua Bloch at QCon New York 2018
• How to Design a Good API and Why It Matters (video) (slides) (PDF) - talk for Google TechTalks by Joshua Bloch in 2006.
• Simple Made Easy - talk by Rich Hickey at Strange Loop 2011
• Łukasz Langa - Keynote from PyCon US 2022
• CLI Guidelines – An open-source guide to help write better command-line programs
• Patterns for Cleaner API Design – 2019 talk recording by Paul Ganssle (slides)
• TellDontAsk by Martin Fowler – Tell-Don’t-Ask is a principle that helps people remember that object-orientation is about bundling data with the functions that operate on that data
• What Does OO Afford? - Sandi Metz (author of ‘99 Bottles of OOP’)
• Affordances and Programming Languages - Randy Coulman
• Affordances from Interaction Design
• APIs as Ladders - Sebastian Bensusan (Stripe)
• Ruby vs Python comes down to the for loop - Doug Turnbull (Shopify)
• How to design APIs that other people like to use - Anna Tisch (Kiwi Pycon X, 2019)