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
120
API Design with Apiary
As presentent on ofmForum.
Z
March 17, 2016
Tweet
Share
More Decks by Z
See All by Z
APIs at the Verge of AI
zdne
0
87
Delivering APIs for AI
zdne
0
260
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
500
Autonomous Integration Mesh '21
zdne
0
170
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
260
Other Decks in Programming
See All in Programming
おやつのお供はお決まりですか?@WWDC25 Recap -Japan-\(region).swift
shingangan
0
140
Git Sync を超える!OSS で実現する CDK Pull 型デプロイ / Deploying CDK with PipeCD in Pull-style
tkikuc
4
240
“いい感じ“な定量評価を求めて - Four Keysとアウトカムの間の探求 -
nealle
2
11k
テストから始めるAgentic Coding 〜Claude Codeと共に行うTDD〜 / Agentic Coding starts with testing
rkaga
15
5.3k
効率的な開発手段として VRTを活用する
ishkawa
0
150
Deep Dive into ~/.claude/projects
hiragram
14
11k
20250704_教育事業におけるアジャイルなデータ基盤構築
hanon52_
5
910
The Evolution of Enterprise Java with Jakarta EE 11 and Beyond
ivargrimstad
0
180
PHP 8.4の新機能「プロパティフック」から学ぶオブジェクト指向設計とリスコフの置換原則
kentaroutakeda
2
1k
Railsアプリケーションと パフォーマンスチューニング ー 秒間5万リクエストの モバイルオーダーシステムを支える事例 ー Rubyセミナー 大阪
falcon8823
5
1.4k
RailsGirls IZUMO スポンサーLT
16bitidol
0
190
なぜ「共通化」を考え、失敗を繰り返すのか
rinchoku
1
670
Featured
See All Featured
Typedesign – Prime Four
hannesfritz
42
2.7k
Performance Is Good for Brains [We Love Speed 2024]
tammyeverts
10
970
VelocityConf: Rendering Performance Case Studies
addyosmani
332
24k
Visualization
eitanlees
146
16k
Fireside Chat
paigeccino
37
3.5k
How to Think Like a Performance Engineer
csswizardry
25
1.7k
Writing Fast Ruby
sferik
628
62k
Dealing with People You Can't Stand - Big Design 2015
cassininazir
367
26k
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
stephaniewalter
281
13k
Music & Morning Musume
bryan
46
6.7k
10 Git Anti Patterns You Should be Aware of
lemiorhan
PRO
656
60k
Bash Introduction
62gerente
613
210k
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