Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Principles of Awesome APIs and How to Build Them.
Search
Keavy McMinn
November 18, 2019
Programming
120
16k
Principles of Awesome APIs and How to Build Them.
Keavy McMinn
November 18, 2019
Tweet
Share
More Decks by Keavy McMinn
See All by Keavy McMinn
Improving your workflow with the GitHub API
keavy
9
670
The Successful Shipper
keavy
8
330
Integrations
keavy
3
440
How to mend a broken identity
keavy
0
140
Better work, through better feedback.
keavy
1
310
Internal Tools
keavy
9
1.4k
Must. Try. Harder.
keavy
0
300
Career Health Check
keavy
0
200
From Artist To Programmer
keavy
1
300
Other Decks in Programming
See All in Programming
1BRC--Nerd Sniping the Java Community
gunnarmorling
0
340
Goのエラースタックトレースの歴史と今後
sonatard
5
380
スクラムガイドのスプリントレトロスペクティブを改めて読みかえしてみた / Re-reading the Sprint Retrospective Section in the Scrum Guide
mackey0225
3
390
#phpcon_odawara オープン・クローズドなテストフィクスチャを求めて / open closed test fixtures
77web
3
220
CQRS/ES avec Symfony, c’est (trop) bien !
jeremyfreeagent
1
640
ONE WEDGE_company_guide
1wedge_one
0
430
入門 AWS Amplify Gen2 / Introduction to AWS Amplify Gen2
genkiogasawara
1
320
Rails と人魚の話/rails-and-mermaid
sanfrecce_osaka
0
100
TYPO3 v13 – The road to LTS: What's new and new APIs
luisasofie_xoxo
0
190
チーム力を高めるスクラム実践法:カンバン公開と課題攻略について - ニフティのスクラムトーク Vol. 2 - NIFTY Tech Talk #18
niftycorp
PRO
1
110
MetricKitで予期せぬ終了を検知する話 / Detect unexpected termination with MetricKit
nekowen
0
180
新宿ダンジョンを可視化してみた
satoshi7190
2
150
Featured
See All Featured
Dealing with People You Can't Stand - Big Design 2015
cassininazir
356
22k
Navigating Team Friction
lara
177
13k
Pencils Down: Stop Designing & Start Developing
hursman
117
11k
The Brand Is Dead. Long Live the Brand.
mthomps
48
28k
Visualizing Your Data: Incorporating Mongo into Loggly Infrastructure
mongodb
34
8.9k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
1
3.4k
個人開発の失敗を避けるイケてる考え方 / tips for indie hackers
panda_program
60
14k
Raft: Consensus for Rubyists
vanstee
132
6.3k
Documentation Writing (for coders)
carmenintech
59
3.9k
From Idea to $5000 a Month in 5 Months
shpigford
377
45k
YesSQL, Process and Tooling at Scale
rocio
163
13k
How GitHub Uses GitHub to Build GitHub
holman
468
290k
Transcript
Principles of Awesome APIs and How to Build Them. Keavy
McMinn, Fastly RubyConf 2019 @keavy
None
None
None
Try to work with the wind, don't fight it all
the time.
Consistent. Stable. Well-documented.
APIs: Our experience as consumers
APIs: Our experience as producers
APIs: Our experience as producers Fixing it would actually break
it.
APIs: Our experience as producers
Application Programming Interface
None
APIs = Constraints
Work with the constraints.
Remember these constraints are good for us too.
None
None
None
Consistent
Consistent Consistent data
✅ { "admin": true } ❌ { "admin": "1" }
API Descriptions — JSON Schema — Open API (formerly Swagger)
— RAML — APIs.json — API Blueprint — Postman Collections — Async API
Consistent Have one source of truth.
Have one source of truth. JSON Schema
JSON Schema committee gem https://github.com/interagent/committee
JSON Schema PRMD gem https://github.com/interagent/prmd
JSON Schema Online examples http://bit.ly/heroku-schema
It will be amaaazing!
Consistent Monitor your inconsistencies.
Monitor your inconsistencies. Compare what you say and what you
do.
Monitor your inconsistencies. Try a portion of your API
Monitor your inconsistencies. Technical deep dive
Monitor your inconsistencies. Technical deep dive https://github.com/whitequark/parser
# Get a dog. get "/dogs/:dog_id" do authorize_access :users, :bots
# finds the dog # renders the dog as JSON end
Then it will be amaaazing!
Stable
Stable Invest 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 are for life not just for Christmas!
https://www.flickr.com/photos/27587002@N07/5170590074
Design while the cost of change is low.
Stable A calm space.
metoffice.gov.uk
Stable
Change itself is not necessarily bad. Negative impact from change
is bad.
Minimize the negative impact
Well-documented
Well-documented Inform users about everything, early and often
Well-documented Then remember that people don’t read.
Well-documented Enable a holistic view. — Endpoints that are undocumented
— Endpoints that are in any special phase — Anything to be deprecated — Dates
Well-documented Governance
Well-documented Shared understanding is easier when it’s all written down.
Well-documented Internal guides
Well-documented API Styleguide
API Styleguide Avoid verbs and adjectives ❌ GET /pets/most-recent ✅
GET /pets?sort=date-added
API Styleguide Make exceptions deliberately GET /repos/:owner/:repo/releases/latest
Well-documented Internal guides
Well-documented Who is responsible for what?
Well-documented Who gets a say in decision making?
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