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
180
API Design with Apiary 2
Z
May 26, 2016
Tweet
Share
More Decks by Z
See All by Z
APIs at the Verge of AI
zdne
0
53
Delivering APIs for AI
zdne
0
250
APIs for AI: Have we failed?
zdne
0
270
AI-enabled APIs
zdne
0
130
Autonomous Agents
zdne
0
130
API Documentation & AI
zdne
0
160
APIs in N-tier architecture
zdne
0
490
Autonomous Integration Mesh '21
zdne
0
160
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
260
Other Decks in Programming
See All in Programming
ニーリーにおけるプロダクトエンジニア
nealle
0
710
LINEヤフー データグループ紹介
lycorp_recruit_jp
0
1.7k
エラーって何種類あるの?
kajitack
5
330
ペアプロ × 生成AI 現場での実践と課題について / generative-ai-in-pair-programming
codmoninc
0
230
新メンバーも今日から大活躍!SREが支えるスケールし続ける組織のオンボーディング
honmarkhunt
1
330
都市をデータで見るってこういうこと PLATEAU属性情報入門
nokonoko1203
1
590
プロダクト志向ってなんなんだろうね
righttouch
PRO
0
170
Modern Angular with Signals and Signal Store:New Rules for Your Architecture @enterJS Advanced Angular Day 2025
manfredsteyer
PRO
0
170
すべてのコンテキストを、 ユーザー価値に変える
applism118
2
1.1k
WindowInsetsだってテストしたい
ryunen344
1
220
AIコーディング道場勉強会#2 君(エンジニア)たちはどう生きるか
misakiotb
1
270
GoのGenericsによるslice操作との付き合い方
syumai
3
710
Featured
See All Featured
Thoughts on Productivity
jonyablonski
69
4.7k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
45
7.5k
Building Flexible Design Systems
yeseniaperezcruz
328
39k
Typedesign – Prime Four
hannesfritz
42
2.7k
KATA
mclloyd
30
14k
Docker and Python
trallard
44
3.5k
Templates, Plugins, & Blocks: Oh My! Creating the theme that thinks of everything
marktimemedia
31
2.4k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
124
52k
The World Runs on Bad Software
bkeepers
PRO
69
11k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
44
2.4k
Being A Developer After 40
akosma
90
590k
Statistics for Hackers
jakevdp
799
220k
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