what tdd can teach us about api design
TRANSCRIPT
@jphenow
What TDD Can Teach Us About API Design
Jon Phenow Highrise
@jphenow
What is TDD?
@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
@jphenow
TDD Benefits
• Proof
• Fast feedback loop
• Test Coverage
• Code Design
@jphenow
TDD’s Effect on Design
• Testable code is usable code
• Explicitly illustrates dependencies of an operaGon
• Exposes difficulty
@jphenow
• Design is affected because of perspecGve
• WriGng as a user
• Not wriGng what’s simple as an author
TDD’s Effect on PerspecGve
@jphenow
PerspecGve is everything
@jphenow
API Design is like UX Design
@jphenow
What’s an API User
• Not user bob vs. user alice
• Topical
@jphenow
An API workflow
• Get a Client Token
• AuthenGcate to receive a user token
• Make requests using this token
@jphenow
Let’s Talk Real World
@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
@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
@jphenow
This sucks
@jphenow
First-glance Problems
• Client admin
• Lots of steps to get something done
• Design of the legacy internals is bleeding out
@jphenow
Dealing with bleeding out
@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
@jphenow
@jphenow
Fix it
• Separate Users
• Your internal choices shouldn’t necessarily bleed out
• DisGll funcGonality and data
@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
@jphenow
Fix it
• Don’t solve for cancelling all rained-out games at once
• Solve for updaGng a group of games with search parameters
@jphenow
Don’t over fix it
• Only a few types of users
• Focus on the 80%
@jphenow
There are limits
• Be protecGve of what you provide
• Performance
@jphenow
Low-FricGon APIs Are a Feature
@jphenow
PerspecGve is the key
@jphenow
Things I didn’t address
• Protocol/Pafern: SOAP/REST
• AuthenGcaGon: SAML/OAuth2/JWT
• API Versioning
@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
@jphenow
@jphenow