Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up for free
API Design with Apiary 2
Z
May 26, 2016
Programming
0
100
API Design with Apiary 2
Z
May 26, 2016
Tweet
Share
More Decks by Z
See All by Z
APIs in N-tier architecture
zdne
0
110
Autonomous Integration Mesh '21
zdne
0
81
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
190
What API: Your Guide to API Styles
zdne
3
970
Consumer APIs Must be Product-Driven
zdne
0
330
Autonomous APIs (Paris 2018)
zdne
1
620
REST vs. GraphQL: Critical Review
zdne
7
150k
Good API Design
zdne
2
570
Autonomous APIs
zdne
1
480
Other Decks in Programming
See All in Programming
TokyoR#103_DataProcessing
kilometer
0
510
tidy_rpart
bk_18
0
560
なぜRubyコミュニティにコミットするのか?
luccafort
0
300
jq at the Shortcuts
cockscomb
1
400
Findy - エンジニア向け会社紹介 / Findy Letter for Engineers
findyinc
2
42k
レガシーフレームワークからの移行
ug
0
100
Step Functions Distributed Map を使ってみた
codemountains
0
100
T3 Stack and TypeScript ecosystem
quramy
3
700
ITエンジニア特化型Q&Aサイトteratailを 言語、DB、クラウドなど フルリプレイスした話
leveragestech
0
380
あなたと 「|」 したい・・・
track3jyo
PRO
2
1k
僕が考えた超最強のKMMアプリの作り方
spbaya0141
0
180
爆速の日経電子版開発の今
shinyaigeek
1
520
Featured
See All Featured
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
239
19k
What's in a price? How to price your products and services
michaelherold
233
9.7k
ParisWeb 2013: Learning to Love: Crash Course in Emotional UX Design
dotmariusz
101
6.2k
Scaling GitHub
holman
453
140k
What's new in Ruby 2.0
geeforr
336
30k
Building Flexible Design Systems
yeseniaperezcruz
314
35k
Agile that works and the tools we love
rasmusluckow
320
20k
StorybookのUI Testing Handbookを読んだ
zakiyama
8
3.2k
Why You Should Never Use an ORM
jnunemaker
PRO
49
7.9k
Learning to Love Humans: Emotional Interface Design
aarron
263
38k
Designing on Purpose - Digital PM Summit 2013
jponch
108
5.9k
Product Roadmaps are Hard
iamctodd
38
7.7k
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