What TDD Can Teach Us About API Design
- 1. @jphenow What TDD Can Teach Us About API Design Jon Phenow Highrise
- 3. @jphenow Test Driven Development • Test first • Run and watch test fail • Fill in the funcGonality that makes the test pass • Run and watch test pass
- 4. @jphenow TDD Benefits • Proof • Fast feedback loop • Test Coverage • Code Design
- 5. @jphenow TDD’s Effect on Design • Testable code is usable code • Explicitly illustrates dependencies of an operaGon • Exposes difficulty
- 6. @jphenow • Design is affected because of perspecGve • WriGng as a user • Not wriGng what’s simple as an author TDD’s Effect on PerspecGve
- 8. @jphenow API Design is like UX Design
- 9. @jphenow What’s an API User • Not user bob vs. user alice • Topical
- 10. @jphenow An API workflow • Get a Client Token • AuthenGcate to receive a user token • Make requests using this token
- 11. @jphenow Let’s Talk Real World
- 12. @jphenow “Real” World • Legacy CMS for Tiered Sports OrganizaGons • Leagues, divisions, teams, games • Third-Party wants to automaGcally update game statuses due to weather informaGon from their system
- 13. @jphenow “Real” World • Call support for an API Key • Copy this key into headers • Query CMS nodes for leagues matching our query • Query each of those for children nodes that are teams • Query each of those for a list of games that would be affected by today’s weather • Update each of those because its too nice out to play baseball today
- 15. @jphenow First-glance Problems • Client admin • Lots of steps to get something done • Design of the legacy internals is bleeding out
- 16. @jphenow Dealing with bleeding out
- 17. @jphenow Bleeding out • Consider who’s using your API • A Sport CMS with an API probably has disGnct two users • Sports/Stats • Content/Site Structure
- 18. @jphenow
- 19. @jphenow Fix it • Separate Users • Your internal choices shouldn’t necessarily bleed out • DisGll funcGonality and data
- 20. @jphenow Recall Some “Real” World • Query CMS nodes for leagues matching our query • Query each of those for children nodes that are teams • Query each of those for a list of games that would be affected by today’s weather • Update each of those because its too nice out to play baseball today
- 21. @jphenow Fix it • Don’t solve for cancelling all rained-out games at once • Solve for updaGng a group of games with search parameters
- 22. @jphenow Don’t over fix it • Only a few types of users • Focus on the 80%
- 23. @jphenow There are limits • Be protecGve of what you provide • Performance
- 24. @jphenow Low-FricGon APIs Are a Feature
- 25. @jphenow PerspecGve is the key
- 26. @jphenow Things I didn’t address • Protocol/Pafern: SOAP/REST • AuthenGcaGon: SAML/OAuth2/JWT • API Versioning
- 27. @jphenow Conclusion • API Design is hard • To the user it should feel fun, simple and powerful • Consider what you have, what they want and express that in an API
- 28. @jphenow
- 29. @jphenow