Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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. Designing APIs
    Like You'd Design Your House
    Alvaro Navarro
    19/01/2023

    View full-size slide

  2. In 2022 I made a mistake

    View full-size slide

  3. …we renovate the kitchen?

    View full-size slide

  4. What happened?
    ● Wrong design
    ● Customers don't speak the same language
    ● Release v2 is going to cost money

    View full-size slide

  5. Alvaro Navarro
    Developer Advocate
    @alnacle

    View full-size slide

  6. Foundation of a sane
    and healthy
    API culture
    Photo by Dose Juice on Unsplash

    View full-size slide

  7. API Guidelines

    View full-size slide

  8. 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

    View full-size slide

  9. API Governance

    View full-size slide

  10. What is an API Governance?
    ● Owners of the guidelines, data dictionaries and
    processes

    View full-size slide

  11. What is an API Governance?
    Example: Track Schema

    View full-size slide

  12. What is an API Governance?
    ● Owners of the guidelines, data dictionaries and
    processes
    ● Technical discussions

    View full-size slide

  13. 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

    View full-size slide

  14. What is an API Governance?
    ● Owners of the guidelines, data dictionaries and
    processes
    ● Technical discussions
    ● API design review

    View full-size slide

  15. 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

    View full-size slide

  16. Why do we need an API Governance?

    View full-size slide

  17. Why API Governance?
    As API Producer
    - Guidelines owners
    - Standardization:
    - Errors
    - Endpoints / parameters naming
    - Improvements
    - Data dictionaries
    - Security
    - Versioning

    View full-size slide

  18. 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

    View full-size slide

  19. 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

    View full-size slide

  20. API Lifecycle
    Photo by Brett Jordan on Unsplash

    View full-size slide

  21. API Lifecycle
    Idea
    - Quick wins
    - Demands from customers
    - Innovation trends
    - Competitors' offering
    - Business goals

    View full-size slide

  22. API Lifecycle
    Idea
    API Design/
    Validation
    Validated by management and legal

    View full-size slide

  23. Design-first approach
    Design

    View full-size slide

  24. Design-first approach
    Design Mocks

    View full-size slide

  25. Design-first approach
    Design Mocks Feedback

    View full-size slide

  26. Design-first approach
    Design Mocks Feedback

    View full-size slide

  27. API Lifecycle
    Idea
    Development
    Testing
    - Beta tester program
    API Design/
    Validation

    View full-size slide

  28. API Lifecycle
    Idea
    Development
    Testing
    Release
    Promotion
    API Design/
    Validation

    View full-size slide

  29. API Lifecycle
    Idea
    Development
    Testing
    Release
    Promotion
    Monitor
    Feedback
    API Design/
    Validation

    View full-size slide

  30. API Lifecycle
    Idea
    Development
    Testing
    Release
    Promotion
    Monitor
    Feedback
    New version?
    API Design/
    Validation

    View full-size slide

  31. API Lifecycle
    Idea
    Development
    Testing
    Release
    Promotion
    Monitor
    Feedback
    Decommission
    API Design/
    Validation
    New version?

    View full-size slide

  32. 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

    View full-size slide

  33. API Lifecycle
    v1 Obsolete supported Obsolete unsupported deprecated
    v2 Obsolete supported Obsolete unsupported deprecated
    v3
    5 months? 5 months?

    View full-size slide

  34. 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

    View full-size slide

  35. 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

    View full-size slide

  36. Recap
    Photo by Júnior Ferreira on Unsplash

    View full-size slide

  37. Recap
    ● Before delivering top-quality APIs, we need establish
    guidelines, tools and processes
    ● API specification is a contract
    ● Always embrace API design-first approach

    View full-size slide

  38. Resources
    https://apideveloperweekly.com/
    https://nordicapis.com/newsletter/
    Newsletters:
    https://apievangelist.com/
    https://apihandyman.io/
    Blogs:

    View full-size slide

  39. developer.spotify.com
    @spotifyplatform
    Thank you!

    View full-size slide