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
140
API Design with Apiary 2
Z
May 26, 2016
Tweet
Share
More Decks by Z
See All by Z
AI-enabled APIs
zdne
0
87
Autonomous Agents
zdne
0
65
API Documentation & AI
zdne
0
110
APIs in N-tier architecture
zdne
0
350
Autonomous Integration Mesh '21
zdne
0
120
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
230
What API: Your Guide to API Styles
zdne
3
1.1k
Consumer APIs Must be Product-Driven
zdne
0
450
Autonomous APIs (Paris 2018)
zdne
1
680
Other Decks in Programming
See All in Programming
Namespace on read
tagomoris
2
370
Introduction of Happy Eyeballs Version 2 (RFC8305) to the Socket library
coe401_
1
220
大規模マルチテナントを解決するYugabyteDBという選択肢
nnaka2992
1
250
Advanced App Shrinking Techniques
cbeyls
2
150
【Go言語】golangci-lintの使い方
tomo1227
0
270
CSC307 Lecture 06
javiergs
PRO
0
360
社内 LT 会を発足し、アウトプット文化を醸成させるために考えたこと・やったこと / Starting internal LT meetings and fostering an output culture
mackey0225
3
120
Async Await: Mastering Python's Time-Bending Tricks - EuroPython2024
yanbo
1
290
Rubyのパフォーマンスプロファイリングの改善 / Enhancing performance profiling for Ruby
osyoyu
1
410
From Spring Boot 2 to Spring Boot 3 with Java 22 and Jakarta EE
ivargrimstad
0
1.9k
【Go言語】ジェネリクス
tomo1227
0
170
CSC307 Lecture 05
javiergs
PRO
0
210
Featured
See All Featured
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
26
1.6k
jQuery: Nuts, Bolts and Bling
dougneiner
61
7.4k
We Have a Design System, Now What?
morganepeng
46
7k
Pencils Down: Stop Designing & Start Developing
hursman
118
11k
A Modern Web Designer's Workflow
chriscoyier
689
190k
Why You Should Never Use an ORM
jnunemaker
PRO
51
8.9k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
228
16k
Bash Introduction
62gerente
607
210k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
189
16k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
35
6.3k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
26
2.1k
For a Future-Friendly Web
brad_frost
173
9.2k
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