What makes a good API for a library? Or more importantly, what makes it bad? This talk discusses the principles of what goes into user-centered design, and how best to apply those principles when writing a Python library for fellow developers.
Blog Post Slidedeck PyTexas Keynote 2024 (slightly longer version) PyCon US 2024
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 #
- 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 #
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)
- Tell Dont Ask 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)