I did the API wrong - Tales of a Library Maintainer
summary
A Clojure library (Liberator) released in 2009 accumulates 320 commits and real users, forcing a maintainer to fix API mistakes rather than redesign. Problems include silent bugs like a missing question mark keyword that makes handlers be ignored, too-many-keyword knobs, macros that block composability, and inconsistent error/state handling. Fixes shown include adding an optional map first-argument to stay backward compatible, explicit exception handlers, and documentation of the execution/context model.
AI-written summary · about
chapters (12)
- 0:00Start
- 7:44A case of miscommunication
- 9:03Use a dedicated error handling model
- 9:18Whatever error model you choose
- 11:30Not so many docstrings...
- 17:12macro apply anyone?
- 22:43Clojure users expect nil punning
- 23:39Missing error handling
- 26:02Problems with too many atoms
- 30:35Nice to avoid endless passing of handles
- 32:47Out of band documentation
- 33:50TODO Liberator uses the ring interface
related talks
27mThe long journey to an API community of practice in an old insurance company
01h 17mDevelopment strategies: You've written a library - now what?
38mA Developer's-Eye View of API Client Libraries
49mOpen sourcing a library: how hard can that be?
05mHow being lazy became a contribution
29mLessons from a Librarian
30mThe Design of Everyday APIs
16mMaintaining an OSS Project (Babel)