What TDD Can Teach Us About API Design
-
Upload
jon-phenow -
Category
Software
-
view
169 -
download
1
Transcript of What TDD Can Teach Us About API Design
![Page 1: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/1.jpg)
@jphenow
What TDD Can Teach Us About API Design
Jon Phenow Highrise
![Page 2: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/2.jpg)
@jphenow
What is TDD?
![Page 3: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/3.jpg)
@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
![Page 4: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/4.jpg)
@jphenow
TDD Benefits
• Proof
• Fast feedback loop
• Test Coverage
• Code Design
![Page 5: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/5.jpg)
@jphenow
TDD’s Effect on Design
• Testable code is usable code
• Explicitly illustrates dependencies of an operaGon
• Exposes difficulty
![Page 6: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/6.jpg)
@jphenow
• Design is affected because of perspecGve
• WriGng as a user
• Not wriGng what’s simple as an author
TDD’s Effect on PerspecGve
![Page 7: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/7.jpg)
@jphenow
PerspecGve is everything
![Page 8: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/8.jpg)
@jphenow
API Design is like UX Design
![Page 9: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/9.jpg)
@jphenow
What’s an API User
• Not user bob vs. user alice
• Topical
![Page 10: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/10.jpg)
@jphenow
An API workflow
• Get a Client Token
• AuthenGcate to receive a user token
• Make requests using this token
![Page 11: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/11.jpg)
@jphenow
Let’s Talk Real World
![Page 12: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/12.jpg)
@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
![Page 13: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/13.jpg)
@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
![Page 14: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/14.jpg)
@jphenow
This sucks
![Page 15: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/15.jpg)
@jphenow
First-glance Problems
• Client admin
• Lots of steps to get something done
• Design of the legacy internals is bleeding out
![Page 16: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/16.jpg)
@jphenow
Dealing with bleeding out
![Page 17: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/17.jpg)
@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
![Page 18: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/18.jpg)
@jphenow
![Page 19: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/19.jpg)
@jphenow
Fix it
• Separate Users
• Your internal choices shouldn’t necessarily bleed out
• DisGll funcGonality and data
![Page 20: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/20.jpg)
@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
![Page 21: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/21.jpg)
@jphenow
Fix it
• Don’t solve for cancelling all rained-out games at once
• Solve for updaGng a group of games with search parameters
![Page 22: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/22.jpg)
@jphenow
Don’t over fix it
• Only a few types of users
• Focus on the 80%
![Page 23: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/23.jpg)
@jphenow
There are limits
• Be protecGve of what you provide
• Performance
![Page 24: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/24.jpg)
@jphenow
Low-FricGon APIs Are a Feature
![Page 25: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/25.jpg)
@jphenow
PerspecGve is the key
![Page 26: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/26.jpg)
@jphenow
Things I didn’t address
• Protocol/Pafern: SOAP/REST
• AuthenGcaGon: SAML/OAuth2/JWT
• API Versioning
![Page 27: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/27.jpg)
@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
![Page 28: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/28.jpg)
@jphenow
![Page 29: What TDD Can Teach Us About API Design](https://reader031.fdocuments.us/reader031/viewer/2022030301/588012171a28ab421b8b7095/html5/thumbnails/29.jpg)
@jphenow