Designing Resilient APIs: Balancing Stability & Flexibility

Delivered at Madison + Ruby 2024

Transcript

1. API
2. Awesome People Interface
3. Awesome People Interface
4. Awesome People Interface
5. Awesome People Interface
6. Designing Resilient APIs: Balancing Stability & Flexibility MADISON + RUBY 2024 | Mark Yoon
7. Resilient APIs Definitions • Definitions • Why is this hard? • What should we do? • How should we do it? • What’s missing?
8. Interface Contract that defines how two systems interact API defines how two applications interact Web API presents that interaction over a network
9. A good interface Operational - does what you want, in the way you want it Expressive - provides clear options to do what you want Simple - makes common uses easy, advanced uses possible Predictable - relies on well-known patterns Adapted from API Design Patterns, JJ Geewax
10. A good interface Operational - does what you want, in the way you want it Expressive - provides clear options to do what you want Simple - makes common uses easy, advanced uses possible Predictable - relies on well-known patterns Resilient
11. Resilient Capable of adapting easily to change (cockroaches, ants) Adapts to changes, but without disruption or loss Business cycle, not request / response cycle Enhances trust and satisfaction
12. Resilient APIs Why is this hard? • Definitions • Why is this hard? • What should we do? • How should we do it? • What’s missing?
13. Change is constant Users want more functionality Businesses want growth The world around us shifts https://xkcd.com/1770/
14. Adapted from API Design Patterns, JJ Geewax Flexibility Visibility Example Change Flexible Private Internal site Easy Flexible Public Public site Moderate Stable Private Internal API Difficult Stable Public Public API VERY HARD But sometimes, change is hard
15. Web development Deployment nearly instant Upgrades can be universal GUIs are used by flexible humans Back / front-end often tightly coupled https://xkcd.com/1172/
16. App development App store process lag time Previous versions persist APIs are used by rigid code Back / front end often distinct teams https://xkcd.com/1172/
17. Resilient APIs What should we do? • Definitions • Why is this hard? • What should we do? • How should we do it? • What’s missing?
18. Options Plan for change Resilient Paced innovation Takes time and care Enables growth Never change High stability Limited innovation Rarely possible Stifles growth Change recklessly High flexibility & risk Rapid innovation Alienates your users Undermines growth
19. Use standard methods Standard methods drive consistency and predictability Generally avoid side effects, strive for idempotency Custom methods are useful for state changes Adapted from API Design Patterns, JJ Geewax
20. Standardize errors Use 4xx codes consistently across the API Error response should contain • code - machine readable, does not change • details - structured, machine readable information • message - human readable, can change
21. Pick a versioning strategy Zombie - v1 lives forever Sliding window - preview, current, deprecated Semantic - lots of versions to maintain https://xkcd.com/1459/
22. Plan for backwards compatibility Optimizations & under-the-hood changes Bug fixes New functionality Mandatory changes Semantic changes “Time to upgrade” Adapted from API Design Patterns, JJ Geewax
23. Name good Use the same name to represent the same thing and different names to represent different things. Make a decision - pick something and stick with it Imperative mood - “get errors” Indicative mood - “is valid” Adapted from API Design Patterns, JJ Geewax
24. Use design patterns Long running operations and re-runnable jobs References and associations Pagination, filtering, importing and exporting Authentication, re-tries, and de-duplication API Design Patterns JJ Geewax
25. Resilient APIs How should we do it? • Definitions • Why is this hard? • What should we do? • How should we do it? • What’s missing?
26. Start on the same team “Same team” Ideally coupled Multiple perspectives Low-cost collaboration Same person Tightly coupled One perspective No collaboration Separate teams Loosely coupled Multiple perspectives Higher-cost collaboration
27. Design - sketch it out Start with the user Product and design intent Concrete draft in a collaborative space, allow for comments Three lists: must do, might do, and won’t do
28. Development - use it right away Start with static, fake data Dynamic fake data, sampled real data Test edge cases and error handling
29. Deployment - use it for real Deploy behind a feature flag Ship app changes Test internally … 🚀 Release to the world https://xkcd.com/2107/
30. How much business logic can live on the client? Null vs. empty Errors Naming Document - write out decisions
31. Plan to change with care Work with others, on the same team Take the imaginary, and make it concrete General approach
32. Resilient APIs What’s missing? • Definitions • Why is this hard? • What should we do? • How should we do it? • What’s missing?
33. Designing Resilient APIs: Balancing Stability & Flexibility MADISON + RUBY 2024 | Mark Yoon