Heard of Twilio? It's the $2.4B cloud communications company behind 2016's hottest IPO. You use it everyday without knowing it. The text message saying your Uber arrived? Twilio sent it. When you lose your Netflix password? They have you covered. Considered as one of the most innovative & developer-friendly company out there today, if there's something they got right it's the product! We were glad to have Andrew Jordan, ex-Product Manager and early employee at Twilio share his experience on stage! In this talk, Jordan explains API design and principles, covering how to identify a good opportunity for an API, how to write a well defined API spec and how to gather user feedback and iterate on APIs. Before quitting his job to travel, spent the last five years designing, building, and selling APIs at Twilio. The last product he shipped was a speech recognition API for the company's voice product. Once he's done traveling, he plans to look into new ideas around speech processing and insurance.

1. REST API DESIGN
END TO END

2. ANDREW JORDAN
PRODUCT MANAGER
@andrewkirk
andrew@akjordan.com

3. BIT.LY/2TSLMHD
DOWNLOAD PDF OF SLIDES HERE

4. ON TODAY’S AGENDA
END TO END REST API DESIGN
▸ API as a Business Model
▸ API Flavors
▸ Resource Design
▸ Testing and Feedback
▸ Resources for Further Reading
▸ Questions

5. API FIRST AS A BUSINESS MODEL
CLEAN AND SIMPLE
MESSY AND HARD
YOUR CLIENTS
YOUR API
YOUR SERVICES

6. API FIRST AS A BUSINESS MODEL

7. API FIRST AS A BUSINESS MODEL
▸ “Solve hard problems for which customers will pay”
▸ Founded in 2007, IPO in 2016 for 2.8 Billion
▸ Twilio Voice API
▸ 100+ million API requests a day
▸ $100+ million ARR business
▸ 99.999% Uptime
▸ 99.999% Request Success Rate

8. FLAVOR
DEFINE YOUR API

9. API FLAVOR
DEFINE YOUR API FLAVOR
▸ Choose HTTP methods that will be supported
▸ Choose the data interchange formats that will be accepted and returned
▸ Choose the format for dates, times that will be used
▸ Define what fields must always be returned for every response

10. API FLAVOR
DEFINE YOUR API FLAVOR
▸ The sum of these decisions dictate the flavor of your API, having a flavor makes
your API predictable to use across endpoints.
▸ At minimum these decisions need to be codified in a style guide and enforced
by people, at scale these need to be enforced with tests.
▸ In the absence of the time to do the above, copy the design decisions of a
good API.

11. ACCEPTS URLENCODED PARAMS RETURNS JSON FLAVORED API - “TWILIO FLAVOR”
REQUEST
curl -X POST https://api.thefamily.co/v1/talks
-d ‘speaker_name=Andrew%20Jordan
-d ‘topic=End%20to%20End%20REST%20API%20Design’
-u ‘[Username]:[Password]’
-H 'content-type: application/x-www-form-urlencoded'

12. ACCEPTS URLENCODED PARAMS RETURNS JSON FLAVORED API - “TWILIO FLAVOR”
RESPONSE
201 Created
{
"guid": "7abb4f67-84dc-4ddb-9f33-8d0410e8bacd",
"date_created": "2017-06-17T11:17:32Z",
"date_updated": “2017-06-17T11:17:32Z",
“speaker_name": “Andrew Jordan”,
"topic": "End to End REST API Design",
"uri": "api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd.json",
"subresource_uris": {
“slides": "api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd/slides.json",
“videos": “api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd/
videos.json”
}

13. PREDICTABILITY
APIS ARE CONTRACTS, CONTRACTS PROVIDE

14. Written Spec Tech Spec Internal Testing External Testing GA

15. Written Spec Tech Spec Internal Testing External Testing GA
COSTS OF CHANGES INCREASE EXPONENTIALLY
RATE OF CHANGE SHOULD DROP OVER TIME

16. Written Spec Tech Spec Internal Testing External Testing GA

17. DESIGNING FOR PREDICTABILITY
UNDERSTAND YOUR CUSTOMER AND THEIRS
▸ API Design is “Meta” Product Management
▸ Your customer is the developer, but they have a customer too.
▸ What is the developer trying to build?
▸ What do the developer’s customers care about?

18. DESIGNING FOR PREDICTABILITY
WRITE A NARRATIVE FOR YOUR API
▸ Generate a document that details the problem, your customer interviews and
preliminary API design.
▸ This doc is for you as a PM and your engineering team to work out the rough details
of the API.
▸ This doc is the seed of your documentation
▸ Engineering should sign off this doc to flag any security or scaleability issues early
▸ A cleaned up version of this doc should be shared with customer as early as
possible for feedback

19. DESIGNING FOR PREDICTABILITY
DEFINE YOUR RESOURCES
▸ Every resource should be a noun, not a verb
▸ Choosing the correct level of abstraction is the art of API design
▸ Expose a minimal number of resource properties to start
▸ 80% or more of the time spent designing an API is spent taking the underlying
system and translating it into an object model that makes sense
▸ This underlying structure is most disruptive to change so spend the most time
getting it right

20. Written Spec Tech Spec Internal Testing External Testing GA

21. DESIGNING FOR PREDICTABILITY
TECHNICAL SPECIFICATION
▸ Document laying out object model, request flow, sequence diagrams
▸ If you are using Swagger or similar, this is where you start generating those
specifications
▸ Once technical specification is finalized feed any changes back into your
written narrative and validate changes with your customers.

22. Written Spec Tech Spec Internal Testing External Testing GA

23. DESIGNING FOR PREDICTABILITY
INTERNAL TESTING
▸ As a Product Manager building an API, you are your first customer, code
against your API early and often.
▸ Evaluate the usability of your API
▸ Generate code samples to use in your documentation

24. DESIGNING FOR PREDICTABILITY
INTERNAL TESTING
▸ Plan an internal hackathon to build against your API, treat your team like your
customers.
▸ Detail out several use cases that they should be able to build.
▸ Customer facing docs should be completed by this point, do not allow use of
internal docs.
▸ Improve customer facing docs as hackathon progresses.
▸ Keep shared google sheet for team to compile issues

25. Written Spec Tech Spec Internal Testing External Testing GA

26. DESIGNING FOR PREDICTABILITY
EXTERNAL TESTING
▸ Define release stages for your API and clearly communicate them, for instance
Preview, Beta, GA
▸ Preview APIs could have significant breaking changes, and may not be
totally operationalized
▸ Beta APIs may have small breaking changes should be production ready
▸ GA APIs had no breaking changes allowed without a version change, fully
operationalized with SLAs

27. DESIGNING FOR PREDICTABILITY
EXTERNAL TESTING
▸ Getting good customer feedback for an API is incredibly difficult
▸ Customers don't want to do throw away development work integrating an API
that will significantly change. Customers want to engage once API is nearly
final, without customer feedback API will never be final, goto 1.
▸ Hackathons + Amazon cards work pretty well, paid user testing, cultivate a few
customers that you take very good care of in exchange for their API feedback.
▸ The Beta stage is where you need to start selling your API, lag time to integrate
can be months, need to get your API on dev schedules in advance.

28. Written Spec Tech Spec Internal Testing External Testing GA

29. DESIGNING FOR PREDICTABILITY
GENERAL AVAILABILITY
▸ In the best case, having an API in GA should be very low overhead, predicable
▸ Documentation is a never-ending maintenance task, it can always be better
▸ Fix bugs (some of them), improve API performance
▸ Gather feedback for future enhancements

30. DESIGNING FOR PREDICTABILITY
IF YOU HAVE TO CHANGE, DO SO CAREFULLY
▸ Plan for and document your change policy, clearly communicate it to your
customers.
▸ Additive changes are usually safe
▸ Add new resources or new parameters to resources
▸ Add new subdomains for new products

31. DESIGNING FOR PREDICTABILITY
IF YOU HAVE TO CHANGE, DO SO CAREFULLY
▸ Versioning is a massive undertaking and has very large indirect costs.
▸ Will need to maintain parallel, docs, support FAQ everything, may double
your overhead to maintain API.
▸ Version with a non date identifier, https://api.thefamily.co/v1/talks to https://
api.thefamily.co/v2/talks
▸ “We’ll just migrate the last few customers off the old endpoint and shut it
down”

32. DESIGNING FOR PREDICTABILITY
▸ Predictability, consistency, and stability above all else.
▸ APIs are a contract, define a clear contact and honor it.
▸ Use GUIDs or UUIDs as resource identifiers
▸ All time in ISO 8601, in UTC, always
▸ Version APIs using version numbers, not dates
▸ Separate APIs should live on Subdomains
▸ Implement HATEOS
▸ Start small and make additive non-breaking changes
▸ Basic auth is probably fine, a scoped token scheme is better, think about how auth impacts developer experience.
▸ HTTPS only and always
▸ Customer feedback on APIs is hard to come by, plan on doing most of the lifting internally.
TAKEAWAYS

33. WRITING AND TALKS
▸ Amanda Folson, Your API is Bad and
you should Feel Bad
▸ Vinay Sahni: API Best Practices
▸ Gordon Wintrob's GET PUT POST
newsletter
▸ Kevin Burke on API Docs
▸ Kevin Burke on Client Libs
▸ And the other talks from API Mixtape
conference
API EXAMPLES
▸ Classic Flavor Twilio API
▸ Modern Flavor Twilio API
▸ Shippo API
▸ Stripe API
▸ 18F API Standards
▸ Microsoft API Guidelines
FURTHER CONTENT
TOOLING
▸ Swagger
▸ POSTman

34. QUESTIONS?

35. CUT SLIDES

36. REST
Request:
curl -G http://api.thefamily.co/v1/talks
-u ‘23679019-81dd-4c24-83c5-2b625c71186c:e592b87e-3c5f-4fed-8d8f-a1edbc88c880'
Response:
200 OK
{
"uri": "api.thefamily.co/v1/talks.json",
"first_page_uri": "api.thefamily.co/v1/talks?Page=0",
"previous_page_uri": null,
"next_page_uri": "api.thefamily.co/v1/talks?Page=1",
"talks": [{
"guid": "7abb4f67-84dc-4ddb-9f33-8d0410e8bacd",
"date_created": "Friday, 30-Jun-17 11:17:32 UTC",
"date_updated": "Friday, 30-Jun-17 11:17:32 UTC",
"speaker_name": “Andrew Jordan”,
"topic": "End to End REST API Design",
"uri": "api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd.json",
"subresource_uris": {
"slides": "api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd/slides.json",
"recordings": "api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd/slides/recordings.json"}},
{
"guid": "a680011a-5286-4d10-96b8-a9cbcfbd1d08",

37. REST
Request:
curl -G http://api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd.json
-u ‘23679019-81dd-4c24-83c5-2b625c71186c:e592b87e-3c5f-4fed-8d8f-a1edbc88c880'
Response:
200 OK
{
“guid": "7abb4f67-84dc-4ddb-9f33-8d0410e8bacd",
"date_created": "Friday, 30-Jun-17 11:17:32 UTC",
"date_updated": "Friday, 30-Jun-17 11:17:32 UTC",
“speaker_name": “Andrew Jordan”,
"topic": "End to End REST API Design",
"uri": "api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd.json",
"subresource_uris": {
"slides": "api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd/slides.json",
“recordings": “api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd/slides/recordings.json”
}

38. REST
Request:
curl -X POST http://api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd.json
-d ‘topic=Front%20to%20Back%20REST%20API%20Design’
-u ‘23679019-81dd-4c24-83c5-2b625c71186c:e592b87e-3c5f-4fed-8d8f-a1edbc88c880'
-H 'content-type: application/x-www-form-urlencoded'
Response:
201 Created
{
"guid": "7abb4f67-84dc-4ddb-9f33-8d0410e8bacd",
"date_created": "Friday, 30-Jun-17 11:17:32 UTC",
"date_updated": "Friday, 30-Jun-17 13:42:32 UTC",
“speaker_name": “Andrew Jordan”,
"topic": "Front to Back REST API Design",
"uri": "api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd.json",
"subresource_uris": {
"slides": "api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd/slides.json",
“recordings": “api.thefamily.co/v1/talks/7abb4f67-84dc-4ddb-9f33-8d0410e8bacd/slides/recordings.json”
}

39. REST
Request:
curl -X DELETE http://api.thefamily.co/v1/talks/
7abb4f67-84dc-4ddb-9f33-8d0410e8bacd.json
-u ‘23679019-81dd-4c24-83c5-2b625c71186c:e592b87e-3c5f-4fed-8d8f-
a1edbc88c880'
Response:
204 No Content

40. API FLAVOR
WHAT IS REST
▸ REST (Representational State Transfer) is an architectural style which advocates
that web applications should use HTTP as it was originally envisioned. Lookups
should use GET requests. PUT, POST, and DELETE requests should be used for
creation, mutation, and deletion.
▸ Create, Read, Update, Delete (CRUD) maps to POST, GET, PUT/PATCH, DELETE