What TDD Can Teach Us About API Design

@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