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

The Great API Redesign (API Conference 2018)

The Great API Redesign (API Conference 2018)

Redesigning a public web service API is a major undertaking: 3 years, thousands of hours of work, new clients, new documentation, a series of releases… This is the story of the DNSimple API v2, a project that started with a single, innocuous GitHub pull request with the title "Proposal for versioned API" in December 2013, and which came to a successful general availability launch at the end of 2016. Simone will explain some of the decisions that the team took over the last 3 years that shaped the development of the API as well as challenges the team faced, and provide you with tips and techniques that may help you in your next major API project. Finally, the important question: what’s next?

Simone Carletti

April 12, 2018
Tweet

More Decks by Simone Carletti

Other Decks in Programming

Transcript

  1. The Great API Redesign
    Simone Carle7, DNSimple

    View Slide

  2. View Slide

  3. @weppos

    View Slide

  4. View Slide

  5. "This PR is a first step towards API versioning and
    using a dedicated hostname for API."

    View Slide

  6. "This PR is a first step towards API versioning and
    using a dedicated hostname for API."
    Dec 28, 2013

    View Slide

  7. Dec 28, 2013
    v0
    API v0

    View Slide

  8. API v0
    • Same hostname as website
    • No versioning
    • No metrics
    • Shared Rails controllers

    View Slide

  9. It worked ™

    View Slide

  10. GET https://dnsimple.com/domains.json
    GET https://dnsimple.com/domains.json

    View Slide

  11. Jan 14, 2014
    Dec 28, 2013
    v0 v1
    API v1

    View Slide

  12. API v1
    • Introduce hostname api.dnsimple.com
    • Introduce path-based versioning
    • SFll uses the same Rails controllers
    • Simple transiFon through minimal changes

    View Slide

  13. GET https://api.dnsimple.com/v1/domains

    View Slide

  14. Why a separate hostname?
    • Easily flag requests as API requests
    • Improved error handling due to clear indicaFon of what
    is an API call
    • Adds the ability to extract API code from controllers
    • Provides easier scaling

    View Slide

  15. Why path-based versioning?
    The approach I followed is simple.
    May be not the most restful, but it's the one very
    commonly adopted that will also allow us to
    switch to a mime-based approach (in case we
    want to follow that route in the future).

    View Slide

  16. Why path-based versioning?
    • API version is embedded in the path and it prefixes the URL
    • Everything in the URL is easily visible in logs
    • Easiest implementaFon for both producFon and
    consumpFon
    • HiSng path-based versioned APIs with a browser is easy
    • New versions increase the major number
    • Path and verb changes can be introduced at major version

    View Slide

  17. Jan 14, 2014
    Dec 28, 2013
    v0 v1
    API v1

    View Slide

  18. Jan 14, 2014
    Dec 28, 2013
    v0 v1 v2
    API v2

    View Slide

  19. Separate ApplicaIon
    • Use of a separate
    (sub)applicaFon
    • No longer Fghtly coupled to
    the Rails controllers
    hWp:/
    /hanamirb.org
    hWp:/
    /confreaks.tv/videos/railsconf2016-developing-and-maintaining-a-pla\orm-with-rails-and-lotus

    View Slide

  20. the Roadmap
    • MulF-account
    • Reusable shared business logic
    • Response serializaFon
    • PaginaFon, SorFng and Filtering
    • AuthenFcaFon
    • Rate limiFng
    • Webhooks
    • API clients

    View Slide

  21. View Slide

  22. View Slide

  23. May 2, 2016
    API clients
    Java PHP
    May 2, 2016 Sep 6, 2016 Sep 13, 2016
    hWps:/
    /slidr.io/weppos/using-go-to-guide-api-design-decisions-dotgo-2016

    View Slide

  24. API clients
    • Developing clients gets easier with each new client
    • Common design paWerns emerge
    • Shared HTTP fixtures
    • We built a foundaFon for API clients development
    hWps:/
    /blog.dnsimple.com/2017/01/api-client-tesFng-with-hWp-fixtures/

    View Slide

  25. PrioriIes
    • Gathered metrics on v1 endpoint usage
    • PrioriFzed implementaFon based on usage

    View Slide

  26. Jan 14, 2014 Mar 9, 2016 (Beta)
    Dec 13, 2016 (GA)
    Dec 28, 2013
    v0 v1 v2
    API v2

    View Slide

  27. Stats
    • 717 Days from "Start" to "Finish"
    • 3 (almost) full-Fme team members out of 11 total, with a
    collaboraFve effort from the enFre DNSimple team
    • 4 official API clients, with 2 more under development
    • 75 API methods currently available (*)
    • 251 Ickets across 7 major milestones
    • ~423 API related support Ickets handled in the last year
    • ~1934 commits across the 4 API clients and applicaFon

    View Slide

  28. What's next?
    • Adopt a formal language to describe the API
    • Deprecate and shut down API v1
    • Facilitate transiFon to API v2
    • Implement new methods (e.g. cerFficate, pricing)

    View Slide

  29. Open API
    hWps:/
    /www.openapis.org/

    View Slide

  30. hWps:/
    /blog.dnsimple.com/2018/02/openapi/

    View Slide

  31. hWps:/
    /blog.dnsimple.com/2018/04/openapi-in-depth/

    View Slide

  32. View Slide

  33. TransiIon to v2
    Measure Facilitate Deprecate

    View Slide

  34. TransiIon to v2
    Measure Facilitate
    Deprecate

    View Slide

  35. TransiIon to v2
    Measure Facilitate
    Deprecate

    View Slide

  36. TransiIon to v2
    Measure Facilitate
    Deprecate

    View Slide

  37. TransiIon to v2
    Measure Facilitate
    Deprecate

    View Slide

  38. TransiIon to v2
    Measure Facilitate

    View Slide

  39. Lessons
    • Simple transiFon through minimal changes
    • Be a producer and a consumer
    • Provide official clients (and/or contribute)
    • Measure decisions
    • Invest into the API

    View Slide

  40. Thanks!
    Simone Carle7 /
    / DNSimple
    hWps:/
    /slidr.io/weppos
    @weppos

    View Slide