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
Search
Z
March 17, 2016
Programming
1
110
API Design with Apiary
As presentent on ofmForum.
Z
March 17, 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
やっと腹落ち「スプリント毎に動くモノをリリースする」〜ゼロから始めるメガバンクグループのアジャイル実践〜
sasakendayo
0
130
お前もAI鬼にならないか?👹Bolt & Cursor & Supabase & Vercelで人間をやめるぞ、ジョジョー!👺
taishiyade
7
4.2k
15分で学ぶDuckDBの可愛い使い方 DuckDBの最近の更新
notrogue
3
830
読まないコードリーディング術
hisaju
0
110
Google Cloudとo11yで実現するアプリケーション開発者主体のDB改善
nnaka2992
0
100
Drawing Heighway’s Dragon- Recursive Function Rewrite- From Imperative Style in Pascal 64 To Functional Style in Scala 3
philipschwarz
PRO
0
150
責務と認知負荷を整える! 抽象レベルを意識した関心の分離
yahiru
8
1.5k
Go 1.24でジェネリックになった型エイリアスの紹介
syumai
2
300
[JAWS DAYS 2025] 最近の DB の競合解決の仕組みが分かった気になってみた
maroon1st
0
160
ナレッジイネイブリングにAIを活用してみる ゆるSRE勉強会 #9
nealle
0
170
iOSでQRコード生成奮闘記
ktcryomm
2
120
たのしいSocketのしくみ / Socket Under a Microscope
coe401_
8
1.4k
Featured
See All Featured
Large-scale JavaScript Application Architecture
addyosmani
511
110k
Speed Design
sergeychernyshev
27
820
Reflections from 52 weeks, 52 projects
jeffersonlam
348
20k
Writing Fast Ruby
sferik
628
61k
Docker and Python
trallard
44
3.3k
The Illustrated Children's Guide to Kubernetes
chrisshort
48
49k
Dealing with People You Can't Stand - Big Design 2015
cassininazir
366
25k
Being A Developer After 40
akosma
89
590k
Navigating Team Friction
lara
183
15k
4 Signs Your Business is Dying
shpigford
183
22k
The Power of CSS Pseudo Elements
geoffreycrofte
75
5.5k
Visualizing Your Data: Incorporating Mongo into Loggly Infrastructure
mongodb
45
9.4k
Transcript
API DESIGN WITH APIARY Z – @zdne Apiary.io
4 STAGES OF API MATURITY API as a by- product
of building apps API documentation generated from code Design-first API Development API Design Consistency
APIARY.IO
DESIGN-FIRST
API DESCRIPTION • API Blueprint • OpenAPI Specification (Swagger) •
Others (RAML, WADL, WSDL, Email, Word document)
API BLUEPRINT
# User [/user] ## Retrieve [GET] Retrieves the . +
Response 200 (application/json) { "name": "John" }
None
None
API LIFECYCLE
Preparation Design Development Delivery Consumption Analysis CLASSIC API LIFECYCLE
Preparation Design & Prototype Development Delivery Consumption Analysis API LIFECYCLE
WITH APIARY
Preparation 1. Define domain semantics 2. Choose architectural style 3.
Define a style guide*
Design & Prototype 1. Formalize API in an API Description
format* 2. Put API Description in a VCS 3. Circulate & Review 4. Apiary Mock Server
Develop 1. API Description in the same repository as implementation
2. Test locally 3. Test with Apiary 4. Test in CI
Deliver 1. Share VCS repository 2. Share Apiary Documentation 3.
Embed Apiary Documentation
Consume 1. Apiary Documentation 2. Apiary Mock Server 3. Documentation
Console 4. Language Examples 5. Apiary Traffic Inspector 6. Apiary Proxy
Analysis
BONUS: GOVERNANCE • Design Rules • Style Guides • Better
DX through CONSISTENCY
BONUS: MSON • Human readable data description • Reusable, format-agnostic
data modeling language • Data is your API
TRY IT NOW http://apiary.io Q&A @apiaryio
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
Feedback Design Delivery Prototype Development SIMPLE API LIFECYCLE
REFERENCE • http://apiary.io • http://apiblueprint.org • https://github.com/apiaryio/mson • http://www.ics.uci.edu/~fielding/pubs/dissertation/ rest_arch_style.htm