API Design Matters

on YouTube ↗30m

" summary

Argument: APIs outlive implementations so design for clients first not implementation. Claims: make APIs easy to learn, minimize surprises, prefer clear names, readable client code, and hard-to-misuse interfaces that avoid ordering and side‑effect coupling. Shows a concrete broken case: Ruby net/http with inconsistent signatures, side‑effecting get_print, and redirect‑by‑exception behavior. Contrasts working tools: Typhoeus, Faraday, open‑uri. Practices: write sample client code, pick good defaults, separate API and SPI, and use semantic versioning for public libraries.

AI-written summary · about

" chapters (27)

1. 0:00Introduction
2. 0:17How many out there
3. 1:07API is our product
4. 1:35API outlives implementations
5. 2:04API leads everything else
6. 2:16Principles
7. 2:31Easy to Learn
8. 3:06readable code
9. 7:02Examples
10. 7:43Consistency
11. 8:57Clarity
12. 9:16Convenience
13. 10:12Conciseness
14. 10:38Example
15. 16:23Shortcut
16. 16:41Post
17. 16:58Faraday
18. 17:48Open URL
19. 18:06Basic Usage
20. 18:37Techniques
21. 19:45Implementation
22. 20:28Client API
23. 22:01API Design Manual
24. 22:40Questions
25. 23:21Refactoring
26. 23:50Chocolate
27. 24:33All code is stuff

" related talks

• 37mYes, You Should Provide a Client Library For Your APIDaniel Azuma · RubyConf 2018
• 22mBuilding the Great Wall: API Driven ApplicationsScott Parker, Dan Melnick · Madison Ruby 2011
• 42mBuilding Better Web APIs with RailsCarlos Souza · Ancient City Ruby 2015
• 45mThe illusion of stable APIsNick Sutterer · RubyConf Colombia 2016
• 42mWeb API's with ERLANG a Ruby Dev's POVPatrick Huesler · Aloha RubyConf 2012
• 41mAPPLICATION ARCHITECTURE: BOUNDARIES, OBJECT ROLES, & PATTERNSAdam Hawkins · wroc_love.rb 2014
• 30mBringing UX to Your CodeJoe Mastey User Centered · RailsConf 2015
• 35mBuilding Ambitious APIs with RubyDan Gebhardt · Burlington Ruby Conference 2013