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
100
API Design with Apiary
As presentent on ofmForum.
Z
March 17, 2016
Tweet
Share
More Decks by Z
See All by Z
AI-enabled APIs
zdne
0
77
Autonomous Agents
zdne
0
50
API Documentation & AI
zdne
0
110
APIs in N-tier architecture
zdne
0
310
Autonomous Integration Mesh '21
zdne
0
110
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
220
What API: Your Guide to API Styles
zdne
3
1.1k
Consumer APIs Must be Product-Driven
zdne
0
430
Autonomous APIs (Paris 2018)
zdne
1
670
Other Decks in Programming
See All in Programming
CA.swift19 恋するAIアプリ開発の裏側
oskmr
0
360
MetricKitで予期せぬ終了を検知する話 / Detect unexpected termination with MetricKit
nekowen
1
180
"config" ってなんだ? / What is "config"?
okashoi
0
240
データアナリストが行うDatabricksを活用したETLの自動化事例
shinoa
0
260
Site Reliability Engineering for GMO
pyama86
7
1k
Fragment Composition of GraphQL
quramy
4
750
R言語の環境構築と基礎 Tokyo.R 112
bob3bob3
0
260
GitHub Actionsで泣かないためにやっておきたい設定 / Recommended GHA settings to avoid crying
pinkumohikan
3
530
スキーマ駆動開発による品質とスピードの両立 - 私達は何故、スキーマを書くのか
kentaroutakeda
0
170
AWS Application Composerで始める、 サーバーレスなデータ基盤構築 / 20240406-jawsug-hokuriku-shinkansen
kasacchiful
1
260
大規模Reactアプリのリアーキテクチャ~8万行のTanStack Query移行の軌跡~
kj455
4
950
Anthropic Cookbook のおすすめレシピ
schroneko
7
900
Featured
See All Featured
Designing on Purpose - Digital PM Summit 2013
jponch
110
6.5k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
227
16k
Debugging Ruby Performance
tmm1
70
11k
Side Projects
sachag
451
41k
Typedesign – Prime Four
hannesfritz
36
2.1k
Facilitating Awesome Meetings
lara
42
5.6k
A Tale of Four Properties
chriscoyier
151
22k
Optimizing for Happiness
mojombo
370
69k
Keith and Marios Guide to Fast Websites
keithpitt
408
22k
Ruby is Unlike a Banana
tanoku
96
10k
YesSQL, Process and Tooling at Scale
rocio
164
13k
We Have a Design System, Now What?
morganepeng
43
6.7k
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