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
170
API Design with Apiary 2
Z
May 26, 2016
Tweet
Share
More Decks by Z
See All by Z
Delivering APIs for AI
zdne
0
200
APIs for AI: Have we failed?
zdne
0
230
AI-enabled APIs
zdne
0
120
Autonomous Agents
zdne
0
98
API Documentation & AI
zdne
0
140
APIs in N-tier architecture
zdne
0
450
Autonomous Integration Mesh '21
zdne
0
150
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
250
What API: Your Guide to API Styles
zdne
3
1.2k
Other Decks in Programming
See All in Programming
.NET Frameworkでも汎用ホストが使いたい!
tomokusaba
0
210
ML.NETで始める機械学習
ymd65536
0
240
AIプログラミング雑キャッチアップ
yuheinakasaka
20
5.1k
5分で理解する SOLID 原則 #phpcon_nagoya
shogogg
1
410
はじめての Go * WASM * OCR
sgash708
1
120
技術を改善し続ける
gumioji
0
180
AIレビュー導入によるCIツールとの共存と最適化
kamo26sima
1
390
Django NinjaによるAPI開発の効率化とリプレースの実践
kashewnuts
1
290
新宿駅構内を三人称視点で探索してみる
satoshi7190
2
120
ナレッジイネイブリングにAIを活用してみる ゆるSRE勉強会 #9
nealle
0
170
PHPカンファレンス名古屋2025 タスク分解の試行錯誤〜レビュー負荷を下げるために〜
soichi
1
740
やっと腹落ち「スプリント毎に動くモノをリリースする」〜ゼロから始めるメガバンクグループのアジャイル実践〜
sasakendayo
0
130
Featured
See All Featured
Code Review Best Practice
trishagee
67
18k
Practical Orchestrator
shlominoach
186
10k
XXLCSS - How to scale CSS and keep your sanity
sugarenia
248
1.3M
KATA
mclloyd
29
14k
Making Projects Easy
brettharned
116
6k
Building Your Own Lightsaber
phodgson
104
6.2k
Testing 201, or: Great Expectations
jmmastey
42
7.2k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
129
19k
GraphQLとの向き合い方2022年版
quramy
44
14k
Why Our Code Smells
bkeepers
PRO
336
57k
BBQ
matthewcrist
87
9.5k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
4
380
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