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
Designing APIs Like You'd Design Your House
Search
Alvaro Navarro
January 20, 2023
Technology
0
130
Designing APIs Like You'd Design Your House
Alvaro Navarro
January 20, 2023
Tweet
Share
More Decks by Alvaro Navarro
See All by Alvaro Navarro
No More Post-its: Boost your login security with APIs
alnacle
0
22
Baking a great DX
alnacle
0
140
Build your first Spotify App
alnacle
0
24
How to use your API Gateway as Developer Relations Tool
alnacle
0
48
Building awesome SDKs for your APIs: Best Practices
alnacle
0
92
DevRel as Professional Career
alnacle
0
190
Effective API Governance: Lessons Learnt
alnacle
0
3.1k
Building a partnership that scales through APIs
alnacle
0
110
The Journey of an OpenAPI platform
alnacle
0
150
Other Decks in Technology
See All in Technology
Bill One 開発エンジニア 紹介資料
sansan33
PRO
4
12k
ゆるSRE #11 LT
okaru
1
590
QAはソフトウェアエンジニアリングを学んで実践するのが大事なの
ymty
1
380
kotlin-lsp を Emacs で使えるようにしてみた / use kotlin-lsp in Emacs
nabeo
0
150
「規約、知識、オペレーション」から考える中規模以上の開発組織のCursorルールの 考え方・育て方 / Cursor Rules for Coding Styles, Domain Knowledges and Operations
yuitosato
6
1.6k
Sansan Engineering Unit 紹介資料
sansan33
PRO
1
2.1k
マルチテナント+マルチプロダクト SaaS への AI Agent の組み込み方
kworkdev
PRO
2
320
TODAY 看世界(?) 是我們在看扣啦!
line_developers_tw
PRO
0
160
Claude Code どこまでも/ Claude Code Everywhere
nwiizo
43
25k
活きてなかったデータを活かしてみた話 / Shirokane Kougyou vol 19
sansan_randd
1
260
Rubyで作る論理回路シミュレータの設計の話 - Kashiwa.rb #12
kozy4324
1
190
Tenstorrent HW/SW 概要説明
tenstorrent_japan
0
390
Featured
See All Featured
Bootstrapping a Software Product
garrettdimon
PRO
307
110k
Keith and Marios Guide to Fast Websites
keithpitt
411
22k
Build The Right Thing And Hit Your Dates
maggiecrowley
36
2.7k
Code Reviewing Like a Champion
maltzj
524
40k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
29
2.6k
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
331
22k
Site-Speed That Sticks
csswizardry
10
630
Practical Orchestrator
shlominoach
188
11k
Building Applications with DynamoDB
mza
95
6.4k
Building Better People: How to give real-time feedback that sticks.
wjessup
367
19k
The Power of CSS Pseudo Elements
geoffreycrofte
77
5.8k
Building Flexible Design Systems
yeseniaperezcruz
328
39k
Transcript
Designing APIs Like You'd Design Your House Alvaro Navarro 19/01/2023
In 2022 I made a mistake
What if…
…we renovate the kitchen?
None
None
None
None
None
None
None
None
None
None
None
None
What happened? • Wrong design • Customers don't speak the
same language • Release v2 is going to cost money
Alvaro Navarro Developer Advocate @alnacle
Foundation of a sane and healthy API culture Photo by
Dose Juice on Unsplash
API Guidelines
Easy-to-consume references and instructions for all of the important information
that a team will need to create or work with APIs API Guidelines
None
API Governance
What is an API Governance? • Owners of the guidelines,
data dictionaries and processes
What is an API Governance? Example: Track Schema
What is an API Governance? • Owners of the guidelines,
data dictionaries and processes • Technical discussions
What is an API Governance? Example: Versioning Using URLs http://api.spotify.com/v1/albums
http://api.spotify.com/2022/albums http://v1.api.spotify.com/albums HTTP Header Accept: application/vnd.spotify.v1 Accept-Version: 1 Query parameter GET /albums?version=1
What is an API Governance? • Owners of the guidelines,
data dictionaries and processes • Technical discussions • API design review
What is an API Governance? Submitted by: awesome_api_designer Reviewers: reviewer_1,
reviewer_2, reviewer_3 • Define the Use Case of the API • Flow (how to use the API) • Data Dictionary • URI • Examples • OpenAPI Spec
Why do we need an API Governance?
Why API Governance? As API Producer - Guidelines owners -
Standardization: - Errors - Endpoints / parameters naming - Improvements - Data dictionaries - Security - Versioning
Why API Governance? As API Producer - Guidelines owners -
Standardization: - Errors - Endpoints / parameters naming - Improvements - Data dictionaries - Security - Versioning As API Consumer - API consistency - Better API integration
Why API Governance? As API Producer - Guidelines owners -
Standardization: - Errors - Endpoints / parameters naming - Improvements - Data dictionaries - Security - Versioning Low participation could create a bottleneck! As API Consumer - API consistency - Better API integration
API Lifecycle Photo by Brett Jordan on Unsplash
API Lifecycle Idea - Quick wins - Demands from customers
- Innovation trends - Competitors' offering - Business goals
API Lifecycle Idea API Design/ Validation Validated by management and
legal
Design-first approach Design
Design-first approach Design Mocks
Design-first approach Design Mocks Feedback
Design-first approach Design Mocks Feedback
API Lifecycle Idea Development Testing - Beta tester program API
Design/ Validation
API Lifecycle Idea Development Testing Release Promotion API Design/ Validation
API Lifecycle Idea Development Testing Release Promotion Monitor Feedback API
Design/ Validation
API Lifecycle Idea Development Testing Release Promotion Monitor Feedback New
version? API Design/ Validation
API Lifecycle Idea Development Testing Release Promotion Monitor Feedback Decommission
API Design/ Validation New version?
API Lifecycle Breaking vs. non-breaking changes Once released, your API
should be considered a contract and cannot be broken without a new version release
API Lifecycle v1 Obsolete supported Obsolete unsupported deprecated v2 Obsolete
supported Obsolete unsupported deprecated v3 5 months? 5 months?
API Lifecycle v1 Obsolete supported Obsolete unsupported deprecated v2 Obsolete
supported Obsolete unsupported deprecated v3 Migration period: support, comms, tutorials, etc. 5 months 5 months
API Lifecycle v1 Obsolete supported Obsolete unsupported deprecated v2 Obsolete
supported Obsolete unsupported deprecated v3 Migration period: specific comms, implement redirects, add "warnings" to the payload 5 months 5 months
Recap Photo by Júnior Ferreira on Unsplash
Recap • Before delivering top-quality APIs, we need establish guidelines,
tools and processes • API specification is a contract • Always embrace API design-first approach
Resources
Resources
Resources https://apideveloperweekly.com/ https://nordicapis.com/newsletter/ Newsletters: https://apievangelist.com/ https://apihandyman.io/ Blogs:
developer.spotify.com @spotifyplatform Thank you!