Design Your APIs Before Laying the First Brick

Transcript

1. 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
2. In 2022 we made a mistake Design Your APIs Before Laying the First Brick APIAddicts 2025 2
3. What if... Design Your APIs Before Laying the First Brick APIAddicts 2025 3
4. ...we renovate the kitchen? Design Your APIs Before Laying the First Brick APIAddicts 2025 4
5. Design Your APIs Before Laying the First Brick APIAddicts 2025 5
6. Design Your APIs Before Laying the First Brick APIAddicts 2025 6
7. Design Your APIs Before Laying the First Brick APIAddicts 2025 7
8. Design Your APIs Before Laying the First Brick APIAddicts 2025 8
9. Design Your APIs Before Laying the First Brick APIAddicts 2025 9
10. Design Your APIs Before Laying the First Brick APIAddicts 2025 10
11. Design Your APIs Before Laying the First Brick APIAddicts 2025 11
12. 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
13. Design Your APIs Before Laying the First Brick APIAddicts 2025 13
14. 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
15. 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
16. 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
17. 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
18. 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
19. API Lifecycle Design Focus on specification Validation with API consumer Design Your APIs Before Laying the First Brick APIAddicts 2025 19
20. API Lifecycle Design Design Your APIs Before Laying the First Brick APIAddicts 2025 20
21. 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
22. API Lifecycle Release Promotion: Webinars, tutorials, etc Design Your APIs Before Laying the First Brick APIAddicts 2025 22
23. API Lifecycle Feedback Evolve the API Potential new version Design Your APIs Before Laying the First Brick APIAddicts 2025 23
24. API Lifecycle Sunset Migration guides Design Your APIs Before Laying the First Brick APIAddicts 2025 24
25. Demo Design Your APIs Before Laying the First Brick APIAddicts 2025 25
26. 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
27. 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
28. { "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
29. Foundation of a sane and healthy API culture Design Your APIs Before Laying the First Brick APIAddicts 2025 29
30. 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
31. Design Your APIs Before Laying the First Brick APIAddicts 2025 31
32. 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
33. 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
34. 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
35. Low participation could create bottleneck! Design Your APIs Before Laying the First Brick APIAddicts 2025 35
36. API Guidelines Demo Design Your APIs Before Laying the First Brick APIAddicts 2025 36
37. 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
38. 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
39. Design Your APIs Before Laying the First Brick APIAddicts 2025 39
40. 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
41. Thank you! alvaro.navarro@vonage.com developer.vonage.com @vonagedev Design Your APIs Before Laying the First Brick APIAddicts 2025 41