Monitor your inconsistencies.
Compare what you say and
what you do.
Slide 31
Slide 31 text
Monitor your inconsistencies.
Try a portion of your API
Slide 32
Slide 32 text
Monitor your inconsistencies.
Technical deep dive
Slide 33
Slide 33 text
Monitor your inconsistencies.
Technical deep dive
https://github.com/whitequark/parser
Slide 34
Slide 34 text
# Get a dog.
get "/dogs/:dog_id" do
authorize_access :users, :bots
# finds the dog
# renders the dog as JSON
end
Slide 35
Slide 35 text
Then it will be amaaazing!
Slide 36
Slide 36 text
Stable
Slide 37
Slide 37 text
Stable
Invest in upfront design.
Slide 38
Slide 38 text
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?
Slide 39
Slide 39 text
Remember:
puppies APIs are
for life not just for
Christmas!
https://www.flickr.com/photos/27587002@N07/5170590074
Slide 40
Slide 40 text
Design while the cost of
change is low.
Slide 41
Slide 41 text
Stable
A calm space.
Slide 42
Slide 42 text
metoffice.gov.uk
Slide 43
Slide 43 text
Stable
Slide 44
Slide 44 text
Change itself is not necessarily
bad.
Negative impact from change is
bad.
Slide 45
Slide 45 text
Minimize the negative
impact
Slide 46
Slide 46 text
Well-documented
Slide 47
Slide 47 text
Well-documented
Inform users about
everything, early and often
Slide 48
Slide 48 text
Well-documented
Then remember that people
don’t read.
Slide 49
Slide 49 text
Well-documented
Enable a holistic view.
— Endpoints that are undocumented
— Endpoints that are in any special phase
— Anything to be deprecated
— Dates
Slide 50
Slide 50 text
Well-documented
Governance
Slide 51
Slide 51 text
Well-documented
Shared understanding is easier
when it’s all written down.
Slide 52
Slide 52 text
Well-documented
Internal guides
Slide 53
Slide 53 text
Well-documented
API Styleguide
Slide 54
Slide 54 text
API Styleguide
Avoid verbs and adjectives
❌
GET /pets/most-recent
✅
GET /pets?sort=date-added
Slide 55
Slide 55 text
API Styleguide
Make exceptions deliberately
GET /repos/:owner/:repo/releases/latest
Slide 56
Slide 56 text
Well-documented
Internal guides
Slide 57
Slide 57 text
Well-documented
Who is responsible for
what?
Slide 58
Slide 58 text
Well-documented
Who gets a say in decision
making?
Slide 59
Slide 59 text
It doesn’t have to be fucking hard.
It just has to be consistent.
Which is fucking hard.
— Brett Sutton, Triathlon coach