Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Sign up for free
Menu
Search
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Pricing
Search
Sign in
Sign up for free
Principles of Awesome APIs and How to Build Them.
Search
Sponsored
·
SiteGround - Reliable hosting with speed, security, and support you can count on.
→
Keavy McMinn
November 18, 2019
Programming
18k
128
Share
Embed
Copy iframe code
Copy JS code
Copy link
Start on current slide
Principles of Awesome APIs and How to Build Them.
Keavy McMinn
November 18, 2019
Transcript
60 slides
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
More Decks by Keavy McMinn
See All by Keavy McMinn
Improving your workflow with the GitHub API
keavy
9
1.2k
The Successful Shipper
keavy
8
610
Integrations
keavy
3
840
How to mend a broken identity
keavy
0
320
Better work, through better feedback.
keavy
1
610
Internal Tools
keavy
9
1.7k
Must. Try. Harder.
keavy
0
690
Career Health Check
keavy
0
380
From Artist To Programmer
keavy
1
540
Other Decks in Programming
See All in Programming
우리의 Nitro Modules는 당신의 Turbo Modules보다 아름답다
l2hyunwoo
0
270
例外からRich Errorsまで Kotlinエラーハンドリングの進化を読み解く
shiita0903
0
210
Spec-driven Development with AI
simas
PRO
0
2.3k
コード生成時代のAPI定義を支えるRequest Spec移行
pvcresin
0
200
なぜ私たちは「現時点では」KMPの導入を見送ったのか
chigichan24
1
290
SODA - FACT BOOK(EN)
sodainc
1
250
はじめてのPLATEAU
nokonoko1203
1
660
RaspberryPi 5で軽くはじめるk3sとtailscaleを用いたホームサーバー構築 (1)
nasum
0
350
AI時代のTerminal環境を UNIX哲学で設計・運用する
yasunori0418
1
360
imagewebp()の向こう側: WebPはなぜ JPEG・PNGより軽いのか
yuzneri
0
120
プロジェクトコードをキレイキレイしよう!暗黙的な参照を読み解く静的解析
ostk0069
0
220
Python Lambdaにおけるテストしやすい設計とAI支援の活用 / Designing Testable Python Lambda Functions with AI
kitano_yuichi
1
330
Featured
See All Featured
4 Signs Your Business is Dying
shpigford
187
23k
A Soul's Torment
seathinner
9
3.9k
The Spectacular Lies of Maps
axbom
PRO
1
1.1k
Bash Introduction
62gerente
615
220k
Getting science done with accelerated Python computing platforms
jacobtomlinson
2
580
Beyond borders and beyond the search box: How to win the global "messy middle" with AI-driven SEO
davidcarrasco
3
300
Bootstrapping a Software Product
garrettdimon
PRO
306
120k
Raft: Consensus for Rubyists
vanstee
143
7.9k
Keith and Marios Guide to Fast Websites
keithpitt
413
23k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
47
8.4k
It's Worth the Effort
3n
188
29k
Building Applications with DynamoDB
mza
96
7.3k