Slide 1

Slide 1 text

The Great API Redesign Simone Carle7, DNSimple

Slide 2

Slide 2 text

No content

Slide 3

Slide 3 text

@weppos

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

Dec 28, 2013 v0 API v0

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

It worked ™

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

No content

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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/

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

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)

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

No content

Slide 33

Slide 33 text

TransiIon to v2 Measure Facilitate Deprecate

Slide 34

Slide 34 text

TransiIon to v2 Measure Facilitate Deprecate

Slide 35

Slide 35 text

TransiIon to v2 Measure Facilitate Deprecate

Slide 36

Slide 36 text

TransiIon to v2 Measure Facilitate Deprecate

Slide 37

Slide 37 text

TransiIon to v2 Measure Facilitate Deprecate

Slide 38

Slide 38 text

TransiIon to v2 Measure Facilitate

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

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