Designing APIs Like You'd Design Your House

Transcript

1. Designing APIs Like You'd Design Your House Alvaro Navarro 19/01/2023
2. In 2022 I made a mistake
3. What if…
4. …we renovate the kitchen?
17. What happened? • Wrong design • Customers don't speak the same language • Release v2 is going to cost money
18. Alvaro Navarro Developer Advocate @alnacle
19. Foundation of a sane and healthy API culture Photo by Dose Juice on Unsplash
20. API Guidelines
21. 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
23. API Governance
24. What is an API Governance? • Owners of the guidelines, data dictionaries and processes
25. What is an API Governance? Example: Track Schema
26. What is an API Governance? • Owners of the guidelines, data dictionaries and processes • Technical discussions
27. 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
28. What is an API Governance? • Owners of the guidelines, data dictionaries and processes • Technical discussions • API design review
29. 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
30. Why do we need an API Governance?
31. Why API Governance? As API Producer - Guidelines owners - Standardization: - Errors - Endpoints / parameters naming - Improvements - Data dictionaries - Security - Versioning
32. 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
33. 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
34. API Lifecycle Photo by Brett Jordan on Unsplash
35. API Lifecycle Idea - Quick wins - Demands from customers - Innovation trends - Competitors' offering - Business goals
36. API Lifecycle Idea API Design/ Validation Validated by management and legal
37. Design-first approach Design
38. Design-first approach Design Mocks
39. Design-first approach Design Mocks Feedback
40. Design-first approach Design Mocks Feedback
41. API Lifecycle Idea Development Testing - Beta tester program API Design/ Validation
42. API Lifecycle Idea Development Testing Release Promotion API Design/ Validation
43. API Lifecycle Idea Development Testing Release Promotion Monitor Feedback API Design/ Validation
44. API Lifecycle Idea Development Testing Release Promotion Monitor Feedback New version? API Design/ Validation
45. API Lifecycle Idea Development Testing Release Promotion Monitor Feedback Decommission API Design/ Validation New version?
46. 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
47. API Lifecycle v1 Obsolete supported Obsolete unsupported deprecated v2 Obsolete supported Obsolete unsupported deprecated v3 5 months? 5 months?
48. 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
49. 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
50. Recap Photo by Júnior Ferreira on Unsplash
51. Recap • Before delivering top-quality APIs, we need establish guidelines, tools and processes • API specification is a contract • Always embrace API design-first approach
52. Resources
53. Resources
54. Resources https://apideveloperweekly.com/ https://nordicapis.com/newsletter/ Newsletters: https://apievangelist.com/ https://apihandyman.io/ Blogs:
55. developer.spotify.com @spotifyplatform Thank you!