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
API Design with Apiary 2
Search
Z
May 26, 2016
Programming
0
130
API Design with Apiary 2
Z
May 26, 2016
Tweet
Share
More Decks by Z
See All by Z
AI-enabled APIs
zdne
0
77
Autonomous Agents
zdne
0
50
API Documentation & AI
zdne
0
110
APIs in N-tier architecture
zdne
0
310
Autonomous Integration Mesh '21
zdne
0
110
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
220
What API: Your Guide to API Styles
zdne
3
1.1k
Consumer APIs Must be Product-Driven
zdne
0
430
Autonomous APIs (Paris 2018)
zdne
1
670
Other Decks in Programming
See All in Programming
二郎系ラーメンのコールで学ぶ AST 解析
memory1994
PRO
7
1.7k
障害対応を起点としたもっといい開発と運用のサイクル作りのためにできること / Hatena Enginner Seminar #29
polamjag
0
180
MicrosoftのPlatform Engineeringガイドを読んで実際になにかやってみた
ymd65536
1
340
Anthropic Cookbook のおすすめレシピ
schroneko
7
980
MetricKitで予期せぬ終了を検知する話 / Detect unexpected termination with MetricKit
nekowen
1
190
Polars入門
daikikatsuragawa
1
100
Build Apps for iOS, Android & Desktop in 100% Kotlin With Compose Multiplatform (mDevCamp 2024)
zsmb
0
340
VSCodeでのDatabricks開発もお勧めしたい/I would also recommend Databricks development with VSCode.
kazumain
0
260
0→1と1→10の狭間で Javaという技術選定を振り返る/Reflecting on the Decision to Choose Java Between Scaling from 0 to 1 and 1 to 10
jaguar_imo
2
380
Site Reliability Engineering for GMO
pyama86
8
1k
What We Can Learn From OSS
inouehi
0
420
GitHub Actionsで泣かないためにやっておきたい設定 / Recommended GHA settings to avoid crying
pinkumohikan
3
540
Featured
See All Featured
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
121
39k
Become a Pro
speakerdeck
PRO
11
4.5k
The Straight Up "How To Draw Better" Workshop
denniskardys
227
130k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
danielanewman
221
21k
ParisWeb 2013: Learning to Love: Crash Course in Emotional UX Design
dotmariusz
104
6.6k
How GitHub Uses GitHub to Build GitHub
holman
468
290k
Writing Fast Ruby
sferik
621
60k
Designing for Performance
lara
601
67k
XXLCSS - How to scale CSS and keep your sanity
sugarenia
241
1.2M
JavaScript: Past, Present, and Future - NDC Porto 2020
reverentgeek
40
4.4k
Faster Mobile Websites
deanohume
299
30k
Visualizing Your Data: Incorporating Mongo into Loggly Infrastructure
mongodb
34
8.9k
Transcript
API DESIGN WITH APIARY Z (@zdne) apiary.io
API DESIGN PLATFORM
API projects managed Developers visit / month 200,000+ 2M
API DESIGN
4 STAGES OF API DESIGN
4 STAGES OF API DESIGN 1 By-product
4 STAGES OF API DESIGN 1 2 By-product Generated Docs
4 STAGES OF API DESIGN 1 2 3 By-product Generated
Docs Design-first
4 STAGES OF API DESIGN 1 2 3 4 By-product
Generated Docs Design-first Design Consistency
IF API IS A PRODUCT TREAT IT AS A PRODUCT
DESIGN-FIRST
EMAIL STORY
EMAIL STORY
EMAIL STORY
EMAIL STORY
RE: RE: RE: RE: RE: RE: RE: RE: API WE
WANT TO BUILD
API DESCRIPTION
API DESCRIPTION • API Blueprint • OpenAPI Specification (Swagger) •
Others (RAML, WADL, WSDL, Email, Word document)
API BLUEPRINT
OPEN API SPEC
API DESIGN WITH APIARY
APIARY API Design API Prototyping API Documentation API Testing API
Debugger API Consistency
APIARY INTEGRATED API Design API Prototyping API Documentation API Testing
API Debugger API Consistency
API DESIGN
API DESIGN API Description • Contract • Product Owner •
Backed Developers • Customers • Tech Writers
API PROTOTYPING
API PROTOTYPING • Automatically generated • Driven by contract •
First-moment of truth • Enables client development Mock Server
API PROTOTYPING
API DOCUMENTATION
API DOCUMENTATION Documentation • Interactive documentation • Automatically generated •
Driven by contract • Language examples • Console
API DOCUMENTATION
API TESTING
API TESTING Tests in CI Local Tests • Verify implementation
• Driven by contract
API TESTING github.com/apiaryio/dredd
API CALL DEBUGGER
API CALL DEBUGGER Call Debugger • Introspect calls • Diff
real vs. expected • Driven by contract
API CALL DEBUGGER
INTEGRATED
CONTRACT-DRIVEN API Description Tests in CI Local Tests Call Debugger
Documentation Mock Server
API FLOW
1 PREPA RATIO N API FLOW D ESIG N D
EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
1 PREPA RATIO N API FLOW D ESIG N &
PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
TRY IT NOW http://apiary.io Q&A @apiaryio
None
apiary.io/how-to-build-api
None
MIND SHIFT • Describe resource NOT representation • Define domain
semantics • Reuse common semantics • Do NOT focus on technical details • URIs • representations • schema validations
API ISN’T… • API is not pretty URLs • API
is not HTTP Verbs • API is not CRUD • API is not JSON
REST ARCHITECTURAL STYLE • Client–server • Stateless • Cacheable •
Layered system • Code on Demand (optional) • Uniform Interface • Identification of resources • Manipulation through representations • Self-descriptive messages • Hypermedia as the engine of the application state
REFERENCE • http://apiary.io • http://apiblueprint.org • https://github.com/apiaryio/mson • http://www.ics.uci.edu/~fielding/pubs/dissertation/ rest_arch_style.htm