WorryFree Computers »
Address
:
[go:
up one dir
,
main page
]
Include Form
Remove Scripts
Accept Cookies
Show Images
Show Referer
Rotate13
Base64
Strip Meta
Strip Title
Session Cookies
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
122
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
700
The Successful Shipper
keavy
8
350
Integrations
keavy
3
460
How to mend a broken identity
keavy
0
150
Better work, through better feedback.
keavy
1
340
Internal Tools
keavy
9
1.4k
Must. Try. Harder.
keavy
0
320
Career Health Check
keavy
0
220
From Artist To Programmer
keavy
1
320
Other Decks in Programming
See All in Programming
ゆるっと話すSLI/SLOを設定してよかったこと出来ていないこと
maaaato
2
490
Optiver参戦記&銀メダル解法
tonic
0
250
LTのやり方
yosuke_furukawa
PRO
11
1.5k
"統合ERP"とアプリケーションアーキテクチャ
keitatomozawa
0
170
ReactNativeでスケジュール帳を作っている話
mokoshi
0
110
Media over QUICとRTMP+HLSの比較
kota_yata
0
110
Project Loom 概要と Scala における有用性 @ ScalaMatsuri2024
th0rikosh1
0
110
Modern Angular Architectures With Nx and Lightweight Stores @ngBelgrade 2024
manfredsteyer
PRO
0
130
CQRS+ES解体新書 / CQRS ES Disassembly Book
nrslib
7
1.5k
FlutterアプリのテストでBuilderパターンを活用しよう
rizumita
0
150
Good intentions gone bad
evaferreira
0
120
Strategien, Taktiken und Muster der Legacy-Ablösung
tobiaslvoss
0
120
Featured
See All Featured
The Illustrated Children's Guide to Kubernetes
chrisshort
33
47k
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
sstephenson
155
14k
4 Signs Your Business is Dying
shpigford
176
21k
Building Flexible Design Systems
yeseniaperezcruz
321
37k
In The Pink: A Labor of Love
frogandcode
138
21k
Faster Mobile Websites
deanohume
300
30k
Imperfection Machines: The Place of Print at Facebook
scottboms
261
12k
The Cult of Friendly URLs
andyhume
74
5.8k
Rebuilding a faster, lazier Slack
samanthasiow
74
8.3k
Build your cross-platform service in a week with App Engine
jlugia
227
17k
Art, The Web, and Tiny UX
lynnandtonic
290
19k
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
323
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