The Great API Redesign (APIStrat 2017)

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?

Transcript

1. The Great API Redesign
   Simone Carle,, DNSimple
   

   View Slide

2. View Slide

3. 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
    • SGll uses the same Rails controllers
    • Simple transiGon 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 indicaGon 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 implementaGon for both producGon and
    consumpGon
    • Hi,ng 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 ApplicaDon
    • Use of a separate
    (sub)applicaGon
    • No longer Gghtly 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
    • MulG-account
    • Reusable shared business logic
    • Response serializaGon
    • PaginaGon, SorGng and Filtering
    • AuthenGcaGon
    • Rate limiGng
    • 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 foundaGon for API clients development
    hWps:/
    /blog.dnsimple.com/2017/01/api-client-tesGng-with-hWp-fixtures/
    

    View Slide

25. PrioriDes
    • Gathered metrics on v1 endpoint usage
    • PrioriGzed implementaGon 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-Gme team members out of 11 total, with a
    collaboraGve effort from the enGre DNSimple team
    • 4 official API clients, with 2 more under development
    • 75 API methods currently available (*)
    • 251 Dckets across 7 major milestones
    • ~423 API related support Dckets handled in the last year
    • ~1934 commits across the 4 API clients and applicaGon
    

    View Slide

28. What's next?
    • Facilitate transiGon to API v2
    • Implement new methods (e.g. cerGficate, pricing)
    • Adopt a formal language to describe the API
    

    View Slide

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

    View Slide

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

    View Slide

31. Thanks!
    DNSimple
    dnsimple.com
    @dnsimple
    Simone CarleS
    simonecarle,.com
    @weppos
    hWps:/
    /slidr.io/weppos
    

    View Slide

32. View Slide