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?

99e0b39c091e10d9c7d4452a34ca52dc?s=128

Simone Carletti

April 12, 2018
Tweet

Transcript

  1. 2.
  2. 3.
  3. 4.
  4. 5.

    "This PR is a first step towards API versioning and

    using a dedicated hostname for API."
  5. 6.

    "This PR is a first step towards API versioning and

    using a dedicated hostname for API." Dec 28, 2013
  6. 8.

    API v0 • Same hostname as website • No versioning

    • No metrics • Shared Rails controllers
  7. 12.

    API v1 • Introduce hostname api.dnsimple.com • Introduce path-based versioning

    • SFll uses the same Rails controllers • Simple transiFon through minimal changes
  8. 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
  9. 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).
  10. 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
  11. 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
  12. 20.

    the Roadmap • MulF-account • Reusable shared business logic •

    Response serializaFon • PaginaFon, SorFng and Filtering • AuthenFcaFon • Rate limiFng • Webhooks • API clients
  13. 21.
  14. 22.
  15. 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
  16. 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/
  17. 26.

    Jan 14, 2014 Mar 9, 2016 (Beta) Dec 13, 2016

    (GA) Dec 28, 2013 v0 v1 v2 API v2
  18. 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
  19. 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)
  20. 32.
  21. 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