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
124
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
730
The Successful Shipper
keavy
8
380
Integrations
keavy
3
500
How to mend a broken identity
keavy
0
160
Better work, through better feedback.
keavy
1
370
Internal Tools
keavy
9
1.5k
Must. Try. Harder.
keavy
0
360
Career Health Check
keavy
0
230
From Artist To Programmer
keavy
1
340
Other Decks in Programming
See All in Programming
CSC307 Lecture 09
javiergs
PRO
1
500
Namespace on read
tagomoris
2
370
しくじり先生 Image Matching Challenge 2024 編
goosehaaan
0
810
入社1ヶ月でここまでやった!Findy Toolsインフラ支援の最適化
rvirus0817
6
1.4k
Product Management LT会_クアンド新家
shinshin
0
210
企業向け生成AIアプリの 開発から得られた知見
takaakikakei
0
310
わかりやすい正解を捨てて、コトに向き合う - スクラムフェス金沢2024 スポンサーセッション
yusukekokubo
0
170
ぼっちを避けて楽しむためのアノテコノテ / Various Tips and Tricks to Avoid Loneliness and Have Fun
nrslib
3
1.7k
Polarsの成長: v0.14からv1.0までの変遷と今後の展望
zerebom
1
350
Cloudflare Workers x AWS Lambdaの組み合わせユースケース / Cloudflare Workers x AWS Lambda Combination Use Case
seike460
PRO
2
310
SRE チーム立ち上げ前に考えたこと・取り組んだこと / Considerations and Preparations Before Establishing an SRE Team
mackey0225
3
320
Android開発者のための Kotlin Multiplatform入門
ntaro
0
190
Featured
See All Featured
Building Better People: How to give real-time feedback that sticks.
wjessup
357
18k
Making the Leap to Tech Lead
cromwellryan
127
8.7k
Bash Introduction
62gerente
607
210k
Rebuilding a faster, lazier Slack
samanthasiow
78
8.5k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
129
32k
Into the Great Unknown - MozCon
thekraken
20
1.3k
The Straight Up "How To Draw Better" Workshop
denniskardys
229
130k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
662
120k
Stop Working from a Prison Cell
hatefulcrawdad
266
20k
The MySQL Ecosystem @ GitHub 2015
samlambert
248
12k
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
325
21k
Why Our Code Smells
bkeepers
PRO
332
56k
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