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
127
17k
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
950
The Successful Shipper
keavy
8
510
Integrations
keavy
3
700
How to mend a broken identity
keavy
0
230
Better work, through better feedback.
keavy
1
540
Internal Tools
keavy
9
1.6k
Must. Try. Harder.
keavy
0
550
Career Health Check
keavy
0
310
From Artist To Programmer
keavy
1
450
Other Decks in Programming
See All in Programming
Pythonスレッドとは結局何なのか? CPython実装から見るNoGIL時代の変化
curekoshimizu
5
1.4k
高度なUI/UXこそHotwireで作ろう Kaigi on Rails 2025
naofumi
4
3.6k
株式会社 Sun terras カンパニーデック
sunterras
0
240
NetworkXとGNNで学ぶグラフデータ分析入門〜複雑な関係性を解き明かすPythonの力〜
mhrtech
3
1k
10年もののAPIサーバーにおけるCI/CDの改善の奮闘
mbook
0
790
私はどうやって技術力を上げたのか
yusukebe
43
17k
エンジニアとして高みを目指す、 利益を生み出す設計の考え方 / design-for-profit
minodriven
23
12k
止められない医療アプリ、そっと Swift 6 へ
medley
1
130
Breaking Up with Big ViewModels — Without Breaking Your Architecture (droidcon Berlin 2025)
steliosf
PRO
1
340
猫と暮らすネットワークカメラ生活🐈 ~Vision frameworkでペットを愛でよう~ / iOSDC Japan 2025
yutailang0119
0
220
Go Conference 2025: Goで体感するMultipath TCP ― Go 1.24 時代の MPTCP Listener を理解する
takehaya
7
1.6k
どの様にAIエージェントと 協業すべきだったのか?
takefumiyoshii
2
620
Featured
See All Featured
Build The Right Thing And Hit Your Dates
maggiecrowley
37
2.9k
Six Lessons from altMBA
skipperchong
28
4k
Visualization
eitanlees
148
16k
The Straight Up "How To Draw Better" Workshop
denniskardys
237
140k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
194
16k
JavaScript: Past, Present, and Future - NDC Porto 2020
reverentgeek
52
5.6k
Building Applications with DynamoDB
mza
96
6.6k
10 Git Anti Patterns You Should be Aware of
lemiorhan
PRO
657
61k
Fireside Chat
paigeccino
40
3.7k
Designing for humans not robots
tammielis
254
25k
Build your cross-platform service in a week with App Engine
jlugia
232
18k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
127
53k
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