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
99
API Documentation & AI
zdne
0
140
APIs in N-tier architecture
zdne
0
460
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
Amazon Bedrockマルチエージェントコラボレーションを諦めてLangGraphに入門してみた
akihisaikeda
1
170
楽しく向き合う例外対応
okutsu
0
740
「個人開発マネタイズ大全」が教えてくれたこと
bani24884
1
300
Boost Your Web Performance with Hyperdrive
chimame
1
130
Jakarta EE meets AI
ivargrimstad
0
690
TCAを用いたAmebaのリアーキテクチャ
dazy
0
230
CDKを使ったPagerDuty連携インフラのテンプレート化
shibuya_shogo
0
120
DevNexus - Create AI Infused Java Apps with LangChain4j
kdubois
0
140
iOSでQRコード生成奮闘記
ktcryomm
2
140
もう少しテストを書きたいんじゃ〜 #phpstudy
o0h
PRO
21
4.4k
SwiftUI Viewの責務分離
elmetal
PRO
2
280
AIプログラミング雑キャッチアップ
yuheinakasaka
20
5.3k
Featured
See All Featured
Bootstrapping a Software Product
garrettdimon
PRO
307
110k
Code Reviewing Like a Champion
maltzj
521
39k
Why Our Code Smells
bkeepers
PRO
336
57k
Unsuck your backbone
ammeep
669
57k
It's Worth the Effort
3n
184
28k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
29
2.5k
Making the Leap to Tech Lead
cromwellryan
133
9.1k
For a Future-Friendly Web
brad_frost
176
9.6k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
4
390
A Philosophy of Restraint
colly
203
16k
Fontdeck: Realign not Redesign
paulrobertlloyd
83
5.4k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
231
53k
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