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
99
API Documentation & AI
zdne
0
140
APIs in N-tier architecture
zdne
0
460
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
Boos Performance and Developer Productivity with Jakarta EE 11
ivargrimstad
0
670
The Price of Micro Frontends… and Your Alternatives @bastacon 2025 in Frankfurt
manfredsteyer
PRO
0
180
Go 1.24でジェネリックになった型エイリアスの紹介
syumai
2
310
Rails 1.0 のコードで学ぶ find_by* と method_missing の仕組み / Learn how find_by_* and method_missing work in Rails 1.0 code
maimux2x
1
270
『テスト書いた方が開発が早いじゃん』を解き明かす #phpcon_nagoya
o0h
PRO
9
2.6k
CloudNativePGを布教したい
nnaka2992
0
120
複数のAWSアカウントから横断で 利用する Lambda Authorizer の作り方
tc3jp
0
130
1年目の私に伝えたい!テストコードを怖がらなくなるためのヒント/Tips for not being afraid of test code
push_gawa
1
660
読まないコードリーディング術
hisaju
1
130
楽しく向き合う例外対応
okutsu
0
740
メンテが命: PHPフレームワークのコンテナ化とアップグレード戦略
shunta27
0
320
運用しながらリアーキテクチャ
nealle
0
140
Featured
See All Featured
The World Runs on Bad Software
bkeepers
PRO
67
11k
Designing for Performance
lara
605
68k
KATA
mclloyd
29
14k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
251
21k
How to Think Like a Performance Engineer
csswizardry
22
1.4k
Learning to Love Humans: Emotional Interface Design
aarron
273
40k
VelocityConf: Rendering Performance Case Studies
addyosmani
328
24k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
233
17k
How to train your dragon (web standard)
notwaldorf
91
5.9k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
40
2k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
danielanewman
227
22k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
29
2.5k
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