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
121
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
680
The Successful Shipper
keavy
8
340
Integrations
keavy
3
440
How to mend a broken identity
keavy
0
140
Better work, through better feedback.
keavy
1
320
Internal Tools
keavy
9
1.4k
Must. Try. Harder.
keavy
0
310
Career Health Check
keavy
0
210
From Artist To Programmer
keavy
1
310
Other Decks in Programming
See All in Programming
DMMプラットフォームがTiDB Cloudを採用した背景
pospome
9
4.2k
Exploring the Implementation of “t.Run”, “t.Parallel”, and “t.Cleanup”
akarin
1
110
大規模Reactアプリのリアーキテクチャ~8万行のTanStack Query移行の軌跡~
kj455
4
1k
FigmaとPHPで作る1ミリたりとも表示崩れしない最強の帳票印刷ソリューション
ttskch
43
19k
CA.swift19 恋するAIアプリ開発の裏側
oskmr
0
380
AppRouter Panel Talk
yosuke_furukawa
PRO
1
450
雑に思考を整理する技術と効能
konifar
63
30k
SwiftUIで使いやすいToastの作り方 / How to build a Toast system which is easy to use in SwiftUI
lovee
3
170
TCAとKMPを用いた新規動画配信アプリ 「ABEMA Live」の設計
tomu28
2
130
2 週間で Twitter Bot を作ってみた
contour_gara
0
760
Compose-View Interop in Practice (mDevCamp 2024)
stewemetal
0
160
Anthropic Cookbook のおすすめレシピ
schroneko
7
1.1k
Featured
See All Featured
Reflections from 52 weeks, 52 projects
jeffersonlam
345
19k
How to train your dragon (web standard)
notwaldorf
75
5.2k
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
stephaniewalter
275
13k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
danielanewman
222
21k
Why Our Code Smells
bkeepers
PRO
331
56k
What's new in Ruby 2.0
geeforr
337
31k
Infographics Made Easy
chrislema
238
18k
Code Reviewing Like a Champion
maltzj
515
39k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
20
1.6k
Optimizing for Happiness
mojombo
370
69k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
79
43k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
245
20k
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