"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
• SGll uses the same Rails controllers
• Simple transiGon 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 indicaGon 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 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
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 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
Slide 20
Slide 20 text
the Roadmap
• MulG-account
• Reusable shared business logic
• Response serializaGon
• PaginaGon, SorGng and Filtering
• AuthenGcaGon
• Rate limiGng
• 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 foundaGon for API clients development
hWps:/
/blog.dnsimple.com/2017/01/api-client-tesGng-with-hWp-fixtures/
Slide 25
Slide 25 text
PrioriDes
• Gathered metrics on v1 endpoint usage
• PrioriGzed implementaGon 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-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
Slide 28
Slide 28 text
What's next?
• Facilitate transiGon to API v2
• Implement new methods (e.g. cerGficate, pricing)
• Adopt a formal language to describe the API
Slide 29
Slide 29 text
Open API
hWps:/
/www.openapis.org/
Slide 30
Slide 30 text
Lessons
• Simple transiGon through minimal changes
• Be a producer and a consumer
• Provide official clients (and/or contribute)
• Measure decisions
• Invest into the API