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
970
The Successful Shipper
keavy
8
520
Integrations
keavy
3
700
How to mend a broken identity
keavy
0
240
Better work, through better feedback.
keavy
1
540
Internal Tools
keavy
9
1.6k
Must. Try. Harder.
keavy
0
560
Career Health Check
keavy
0
310
From Artist To Programmer
keavy
1
450
Other Decks in Programming
See All in Programming
iOSエンジニア向けの英語学習アプリを作る!
yukawashouhei
0
200
CSC305 Lecture 04
javiergs
PRO
0
270
テーブル定義書の構造化抽出して、生成AIでDWH分析を試してみた / devio2025tokyo
kasacchiful
0
190
私達はmodernize packageに夢を見るか feat. go/analysis, go/ast / Go Conference 2025
kaorumuta
2
600
CSC305 Lecture 08
javiergs
PRO
0
250
詳しくない分野でのVibe Codingで困ったことと学び/vibe-coding-in-unfamiliar-area
shibayu36
3
5.1k
組込みだけじゃない!TinyGo で始める無料クラウド開発入門
otakakot
1
320
3年ぶりにコードを書いた元CTOが Claude Codeと30分でMVPを作った話
maikokojima
0
570
CSC509 Lecture 06
javiergs
PRO
0
260
The Past, Present, and Future of Enterprise Java
ivargrimstad
0
470
Web フロントエンドエンジニアに開かれる AI Agent プロダクト開発 - Vercel AI SDK を観察して AI Agent と仲良くなろう! #FEC余熱NIGHT
izumin5210
3
570
スキーマ駆動で、Zod OpenAPI Honoによる、API開発するために、Hono Takibiというライブラリを作っている
nakita628
0
190
Featured
See All Featured
Side Projects
sachag
455
43k
Building a Modern Day E-commerce SEO Strategy
aleyda
44
7.8k
BBQ
matthewcrist
89
9.8k
Unsuck your backbone
ammeep
671
58k
Faster Mobile Websites
deanohume
310
31k
GitHub's CSS Performance
jonrohan
1032
470k
Learning to Love Humans: Emotional Interface Design
aarron
274
41k
A Modern Web Designer's Workflow
chriscoyier
697
190k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
140
34k
Rails Girls Zürich Keynote
gr2m
95
14k
Building Better People: How to give real-time feedback that sticks.
wjessup
369
20k
Java REST API Framework Comparison - PWX 2021
mraible
34
8.9k
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