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
110
Delivering APIs for AI
zdne
0
260
APIs for AI: Have we failed?
zdne
0
280
AI-enabled APIs
zdne
0
130
Autonomous Agents
zdne
0
140
API Documentation & AI
zdne
0
170
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
What's new in Adaptive Android development
fornewid
0
130
PHPUnitの限界をPlaywrightで補完するテストアプローチ
yuzneri
0
370
ご注文の差分はこちらですか? 〜 AWS CDK のいろいろな差分検出と安全なデプロイ
konokenj
5
740
新世界の理解
koriym
0
110
新しいモバイルアプリ勉強会(仮)について
uetyo
1
240
NEWT Backend Evolution
xpromx
1
170
はじめてのWeb API体験 ー 飲食店検索アプリを作ろうー
akinko_0915
0
180
Comparing decimals in Swift Testing
417_72ki
0
160
Streamlitで実現できるようになったこと、実現してくれたこと
ayumu_yamaguchi
2
260
kiroでゲームを作ってみた
iriikeita
0
130
TypeScriptでDXを上げろ! Hono編
yusukebe
4
920
decksh - a little language for decks
ajstarks
4
21k
Featured
See All Featured
A Modern Web Designer's Workflow
chriscoyier
695
190k
4 Signs Your Business is Dying
shpigford
184
22k
Into the Great Unknown - MozCon
thekraken
40
2k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
34
6k
Producing Creativity
orderedlist
PRO
346
40k
For a Future-Friendly Web
brad_frost
179
9.9k
Building a Scalable Design System with Sketch
lauravandoore
462
33k
Building a Modern Day E-commerce SEO Strategy
aleyda
43
7.4k
The World Runs on Bad Software
bkeepers
PRO
70
11k
The MySQL Ecosystem @ GitHub 2015
samlambert
251
13k
The Web Performance Landscape in 2024 [PerfNow 2024]
tammyeverts
8
740
Building Better People: How to give real-time feedback that sticks.
wjessup
367
19k
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