Share
Embed
Design Your APIs Before Laying the First Brick
Alvaro Navarro
October 31, 2025
Transcript
41 slides
-
Design Your APIs Before Laying the First Brick Alvaro Navarro
Sr. Developer Experience Engineer Vonage October 22 2025 Design Your APIs Before Laying the First Brick APIAddicts 2025 1 -
In 2022 we made a mistake Design Your APIs Before
Laying the First Brick APIAddicts 2025 2 -
What if... Design Your APIs Before Laying the First Brick
APIAddicts 2025 3 -
...we renovate the kitchen? Design Your APIs Before Laying the
First Brick APIAddicts 2025 4 -
What happened? Wrong design Customers don't speak the same language
v2 release will cost us money Design Your APIs Before Laying the First Brick APIAddicts 2025 12 -
What is Design-First approach? Define the API contract first (endpoints,
inputs, outputs, errors) Then implement the backend based on that contract Involves all stakeholders early (devs, QA, product, partners) Design Your APIs Before Laying the First Brick APIAddicts 2025 14 -
Code-First approach Documentation after the code, often outdated Technical debt
accumulates quickly Teams lose time, motivation, and trust Outcome: Misaligned APIs, wasted effort Design Your APIs Before Laying the First Brick APIAddicts 2025 15 -
Advantages of Design-First Improve collaboration We all understand the API
before coding it We can test the API without backend We can document the API from day one Avoid integration errors and costly fallbacks Design Your APIs Before Laying the First Brick APIAddicts 2025 16 -
When to use Design-First? Always But it’s crucial in scenarios
like: Frontend Backend integrations External API consumers (partners, customers, 3rd parties) Multiple teams working in parallel Fast prototyping & testing with mock servers Design-First reduces risk and speeds up collaboration Design Your APIs Before Laying the First Brick APIAddicts 2025 17 -
API Lifecycle Idea Quick Wins Demands from customers Innovation trends
Competitor's offering Business goals Design Your APIs Before Laying the First Brick APIAddicts 2025 18 -
API Lifecycle Design Focus on specification Validation with API consumer
Design Your APIs Before Laying the First Brick APIAddicts 2025 19 -
API Lifecycle Design Design Your APIs Before Laying the First
Brick APIAddicts 2025 20 -
API Lifecycle Implementation Only if design has been agreed It
usually includes testing phase Design Your APIs Before Laying the First Brick APIAddicts 2025 21 -
API Lifecycle Release Promotion: Webinars, tutorials, etc Design Your APIs
Before Laying the First Brick APIAddicts 2025 22 -
API Lifecycle Feedback Evolve the API Potential new version Design
Your APIs Before Laying the First Brick APIAddicts 2025 23 -
API Lifecycle Sunset Migration guides Design Your APIs Before Laying
the First Brick APIAddicts 2025 24 -
Example The API must return insights (information) about a mobile
phone number, including recent SIM swap status and date, carrier details (name, network type, country code, and network code), and a list of recent calls with timestamps and call direction. Design Your APIs Before Laying the First Brick APIAddicts 2025 26 -
Example Endpoint: /phone-insights/{phoneNumber} Operation: GET (Retrieve phone number insights) Responses:
200 OK , 400 Bad Request and 500 Server Error Design Your APIs Before Laying the First Brick APIAddicts 2025 27 -
{ "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab", "insights": { "sim_swap": { "latest_sim_swap_at": "2024-07-08T09:30:27.504Z", "swapped":
false }, "carrier": { "name": "Mobile Operator, S.A.", "network_type": "MOBILE", "country_code": "ES", }, "recent_calls": [ { "timestamp": "2024-06-29T11:15:00.000Z", "phone_number": "+3460000000", "direction": "incoming" }, { "timestamp": "2024-06-28T14:20:00.000Z", "phone_number": "+3460000000", "direction": "outgoing" } ] } } Design Your APIs Before Laying the First Brick APIAddicts 2025 28 -
Foundation of a sane and healthy API culture Design Your
APIs Before Laying the First Brick APIAddicts 2025 29 -
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. Some Guidelines are public! Design Your APIs Before Laying the First Brick APIAddicts 2025 30 -
API Governance Owner of the guidelines, data dictionaries and processes
Place to have technical discussions around APIs Design Your APIs Before Laying the First Brick APIAddicts 2025 32 -
API Governance - API Design Review Define the Use Case
of the API How to use the API (flow) Data Dictionary URI Examples OpenAPI specification Design Your APIs Before Laying the First Brick APIAddicts 2025 33 -
Why do we need an API Governance? As API Producer
Guidelines owners Standanrization (errors, endpoints, parameters, auth, etc) As API Consumer API consistency Better DX Design Your APIs Before Laying the First Brick APIAddicts 2025 34 -
Low participation could create bottleneck! Design Your APIs Before Laying
the First Brick APIAddicts 2025 35 -
API Guidelines Demo Design Your APIs Before Laying the First
Brick APIAddicts 2025 36 -
Recap Establish guidelines, tools and process to deliver great APIs
API specification is a contract Always embrace API Design-First approach Design Your APIs Before Laying the First Brick APIAddicts 2025 37 -
Tools Client: cURL | Bruno Mock: Prism | Mockoon Linter:
Spectral API Reference: redocly CLI OpenAPI bundle: redocly CLI Design Your APIs Before Laying the First Brick APIAddicts 2025 38 -
Resources Newsletters https://apideveloperweekly.com https://nordicapis.com/newsletter Blogs https://apievengelist.com https://apihandyman.io Design Your APIs
Before Laying the First Brick APIAddicts 2025 40 -
Thank you! [email protected] developer.vonage.com @vonagedev Design Your APIs Before Laying
the First Brick APIAddicts 2025 41