Principles of Awesome APIsand How to Build Them.Keavy McMinn, FastlyRubyConf 2019@keavy
View Slide
Try to work with the wind, don't fightit all the time.
Consistent.Stable.Well-documented.
APIs: Our experience asconsumers
APIs: Our experience asproducers
APIs: Our experience as producersFixing it would actuallybreak it.
Application ProgrammingInterface
APIs = Constraints
Work with the constraints.
Remember these constraints aregood for us too.
Consistent
ConsistentConsistent data
✅{"admin": true}❌{"admin": "1"}
API Descriptions— JSON Schema— Open API (formerly Swagger)— RAML— APIs.json— API Blueprint— Postman Collections— Async API
ConsistentHave one source of truth.
Have one source of truth.JSON Schema
JSON Schemacommittee gemhttps://github.com/interagent/committee
JSON SchemaPRMD gemhttps://github.com/interagent/prmd
JSON SchemaOnline exampleshttp://bit.ly/heroku-schema
It will be amaaazing!
ConsistentMonitor yourinconsistencies.
Monitor your inconsistencies.Compare what you say andwhat you do.
Monitor your inconsistencies.Try a portion of your API
Monitor your inconsistencies.Technical deep dive
Monitor your inconsistencies.Technical deep divehttps://github.com/whitequark/parser
# Get a dog.get "/dogs/:dog_id" doauthorize_access :users, :bots# finds the dog# renders the dog as JSONend
Then it will be amaaazing!
Stable
StableInvest in upfront design.
Invest in upfront design.— What will users do with it?— What does your business need from it?— What does it look like?— What will you call it?
Remember:puppies APIs arefor life not just forChristmas!https://www.flickr.com/photos/[email protected]/5170590074
Design while the cost ofchange is low.
StableA calm space.
metoffice.gov.uk
Change itself is not necessarilybad.Negative impact from change isbad.
Minimize the negativeimpact
Well-documented
Well-documentedInform users abouteverything, early and often
Well-documentedThen remember that peopledon’t read.
Well-documentedEnable a holistic view.— Endpoints that are undocumented— Endpoints that are in any special phase— Anything to be deprecated— Dates
Well-documentedGovernance
Well-documentedShared understanding is easierwhen it’s all written down.
Well-documentedInternal guides
Well-documentedAPI Styleguide
API StyleguideAvoid verbs and adjectives❌GET /pets/most-recent✅GET /pets?sort=date-added
API StyleguideMake exceptions deliberatelyGET /repos/:owner/:repo/releases/latest
Well-documentedWho is responsible forwhat?
Well-documentedWho gets a say in decisionmaking?
It doesn’t have to be fucking hard.It just has to be consistent.Which is fucking hard.— Brett Sutton, Triathlon coach
Good luck!Thank you,@keavy