Upgrade to PRO for Only $50/Year—Limited-Time Offer! 🔥

Designing APIs Like You'd Design Your House

Designing APIs Like You'd Design Your House

Alvaro Navarro

January 20, 2023
Tweet

More Decks by Alvaro Navarro

Other Decks in Technology

Transcript

  1. What happened? • Wrong design • Customers don't speak the

    same language • Release v2 is going to cost money
  2. 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
  3. What is an API Governance? • Owners of the guidelines,

    data dictionaries and processes • Technical discussions
  4. 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
  5. What is an API Governance? • Owners of the guidelines,

    data dictionaries and processes • Technical discussions • API design review
  6. 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
  7. Why API Governance? As API Producer - Guidelines owners -

    Standardization: - Errors - Endpoints / parameters naming - Improvements - Data dictionaries - Security - Versioning
  8. 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
  9. 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
  10. API Lifecycle Idea - Quick wins - Demands from customers

    - Innovation trends - Competitors' offering - Business goals
  11. 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
  12. API Lifecycle v1 Obsolete supported Obsolete unsupported deprecated v2 Obsolete

    supported Obsolete unsupported deprecated v3 5 months? 5 months?
  13. 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
  14. 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
  15. Recap • Before delivering top-quality APIs, we need establish guidelines,

    tools and processes • API specification is a contract • Always embrace API design-first approach