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
126
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
890
The Successful Shipper
keavy
8
470
Integrations
keavy
3
630
How to mend a broken identity
keavy
0
220
Better work, through better feedback.
keavy
1
490
Internal Tools
keavy
9
1.5k
Must. Try. Harder.
keavy
0
500
Career Health Check
keavy
0
300
From Artist To Programmer
keavy
1
420
Other Decks in Programming
See All in Programming
Making TCPSocket.new "Happy"!
coe401_
1
180
AI時代の開発者評価について
ayumuu
0
120
サービスクラスのありがたみを発見したときの思い出 #phpcon_odawara
77web
4
630
「影響が少ない」を自分の目でみてみる
o0h
PRO
2
1k
Day0 初心者向けワークショップ実践!ソフトウェアテストの第一歩
satohiroyuki
0
840
AWS で実現する安全な AI エージェントの作り方 〜 Bedrock Engineer の実装例を添えて 〜 / how-to-build-secure-ai-agents
gawa
8
740
Java 24まとめ / Java 24 summary
kishida
3
490
Firebase Dynamic Linksの代替手段を自作する / Create your own Firebase Dynamic Links alternative
kubode
0
240
5年間継続して開発した自作OSSの記録
bebeji_nappa
0
180
Devin入門と最近のアップデートから見るDevinの進化 / Introduction to Devin and the Evolution of Devin as Seen in Recent Update
rkaga
9
4.8k
マルチアカウント環境での、そこまでがんばらない RI/SP 運用設計
wa6sn
0
710
CRE Meetup!ユーザー信頼性を支えるエンジニアリング実践例の発表資料です
tmnb
0
640
Featured
See All Featured
[RailsConf 2023] Rails as a piece of cake
palkan
54
5.4k
Being A Developer After 40
akosma
91
590k
Docker and Python
trallard
44
3.3k
Bootstrapping a Software Product
garrettdimon
PRO
307
110k
RailsConf 2023
tenderlove
30
1.1k
The World Runs on Bad Software
bkeepers
PRO
67
11k
Keith and Marios Guide to Fast Websites
keithpitt
411
22k
Writing Fast Ruby
sferik
628
61k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
135
33k
How To Stay Up To Date on Web Technology
chriscoyier
790
250k
Fashionably flexible responsive web design (full day workshop)
malarkey
407
66k
Build The Right Thing And Hit Your Dates
maggiecrowley
35
2.6k
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