The document provides an introduction to APIs and their design. It discusses what an API is, how APIs allow software components to interact, and examples of common APIs used like Accuweather, Gmail, Netflix, and Twitter. It also covers REST principles for APIs, including thinking of applications as resources that can be acted upon through HTTP verbs like GET, POST, PUT, and DELETE. Hypermedia and hyperlinks are discussed as ways to connect API resources and allow navigation between them.

1. Introduction to
API Design

2. Understanding APIs
2

3. © LaunchAny, 2016
An application programming interface (API)
specifies how software components should
interact with each other.
3
What is an API?

4. © LaunchAny, 2016
• Accuweather - retrieve the latest weather reports
• Gmail (mobile) - send and receive email from your
phone
• Netflix - rate movies, add/remove from queue
• TripIt - track and receive updates to your travel plans
• Twitter - any interaction with the service
4
APIs you probably already use..

5. © LaunchAny, 2016 5
API Business Models - 2013
http://www.slideshare.net/jmusser/j-musser-apibizmodels2013

6. © LaunchAny, 2016 6
Indirect Model: Store-as-a-Service
API

7. © LaunchAny, 2016
• All new services will be built as modern APIs
• Usability and developer experience are the key
determinants of an acceptable API.
• APIs need to be treated as products with business
leaders understanding and driving the design
• APIs will be designed and built to be externally
consumable (regardless if they are made available to
third-parties)
7
Today’s API Strategy

8. © LaunchAny, 2016
Modern web APIs are the
ultimate “do-over” for
business and IT.

9. © LaunchAny, 2016
Your API design should
become the definition of
your new target
architecture

10. © LaunchAny, 2016
Your API design is
composed of the
capabilities (or “skills”)
you offer to developers

11. © LaunchAny, 2016
API Skills == “I want to…”

16. © LaunchAny, 2016
Mapping Capabilities to API Products

17. © LaunchAny, 2016
The Modular Enterprise
Offers API
Inventory
API
Bookings
API
Identity API
Accounts
API
Rewards API
Partners
Internal
Developers
Public App
Developers
Consumers
Third-party
Approved Apps

18. Order API
List Avail
Inventory
Distributor!
Add Product
to Order
Complete
Order
Cancel
Booking
Add Product
to Inventory
Update
Product Qty
Locate
Booking
Redeem
Booking
Point!
Of Sale!
Remove
Product
Customer!
Operator!
Inventory API
Fulfillment API
Operator!

19. © LaunchAny, 2016
WebApp
API
Product
API
Product
Messaging
…
Microservice
…
API
…
Microservice
…
API
…
Microservice
…API
…
Microservice
…
API
Voice
App
Mobile
App
API
Product
Microservice Architecture

20. © LaunchAny, 2016
Identifying Capabilities
u Business Capabilities
• The “what” at the core – not the “how”
• Capabilities have outcomes/results
• Often tied to revenue or competitive advantages
u Technical Capabilities
• May be “what” or “how” – the processes
• Automation, data and/or data analysis

21. © LaunchAny, 2016
Capability Examples
u Risk management and risk rating
u Inventory management
u Investment management
u Customer management
u Datasets/analytics for specific vertical market
u Unfair/unique technology (e.g. machine learning)

22. © LaunchAny, 2016
Exercise: Identify Capabilities
u List your company’s business and technical capabilities
u Brainstorm individually or in groups
u Capture as many as possible in 5 minutes
u Questions to get started:
• What services do we offer the market that is unique or a
competitive advantage?
• What data or insights do we have that others may be
interested in using to drive their business?
• What processes or tasks could we automate that we
perform manually today?

23. Principles of Modern Web
APIs
23

24. © LaunchAny, 2016
• HTTP is request/response
24
HTTP Primer

25. © LaunchAny, 2016
• Address of where to locate a resource (e.g. web page, image, or API)
• Scheme – How to connect, e.g. http (unsecure) or https (secure)
• Hostname - The server to contact, e.g. api.example.com
• Port number - A number ranging from 0 to 65535 that identifies the
process on the server where the request is to go, e.g. 443 (optional,
defaults to 80 for http and 443 for https)
• Path - The path to the resource being requested, e.g. /projects
(default is /, which indicates the homepage)
• Query String - Contains data to be passed to the server. Starts with
a question mark and contains name=value pairs, using an
ampersand as a separator between them (e.g. ?
page=1&per_page=10)
25
Uniform Resource Locators (URLs)

26. © LaunchAny, 2016 26
URL Example

27. © LaunchAny, 2016
• The request and response have two key parts:
• Header – what you need or what happened
• Body – details (might be empty)
27
HTTP Header and Body

28. © LaunchAny, 2016
GET http://www.google.com/ HTTP/1.0
Proxy-Connection: Keep-Alive
User-Agent: Mozilla/5.0 [en] (X11; I; Linux 2.2.3 i686)
Host: google.com
Accept: image/gif, image/x-xbitmap, image/jpeg, */*
Accept-Encoding: gzip
Accept-Language: en
Accept-Charset: iso-8859-1, *, utf-8
28
HTTP Request

29. © LaunchAny, 2016
GET http://www.google.com/ HTTP/1.0
Proxy-Connection: Keep-Alive
User-Agent: Mozilla/5.0 [en] (X11; I; Linux 2.2.3 i686)
Host: google.com
Accept: image/gif, image/x-xbitmap, image/jpeg, */*
Accept-Encoding: gzip
Accept-Language: en
Accept-Charset: iso-8859-1, *, utf-8
29
HTTP Request

30. © LaunchAny, 2016
HTTP/1.0 200 OK
Date: Tue, 16 June 2015 06:57:43 GMT
Content-Location: http://www.google.com/index.html
Etag: "07db14afa76be1:1074"
Last-Modified: Fri, 15 May 2015 20:01:38 GMT
Content-Length: 7931
Content-Type: text/html
Server: Apache
<html>…
30
HTTP Response

31. © LaunchAny, 2016
HTTP/1.0 200 OK
Date: Tue, 16 June 2015 06:57:43 GMT
Content-Location: http://www.google.com/index.html
Etag: "07db14afa76be1:1074"
Last-Modified: Fri, 15 May 2015 20:01:38 GMT
Content-Length: 7931
Content-Type: text/html
Server: Apache
<html>…
31
HTTP Response

32. © LaunchAny, 2016
HTTP/1.0 200 OK
Date: Tue, 16 June 2015 06:57:43 GMT
Content-Location: http://www.google.com/index.html
Etag: "07db14afa76be1:1074"
Last-Modified: Fri, 15 May 2015 20:01:38 GMT
Content-Length: 7931
Content-Type: text/html
Server: Apache
<html>…
32
HTTP Response

33. © LaunchAny, 2016
• REpresentational State Transfer (REST)
• REST is a distributed (client-server) architecture
focused on separating concerns while encouraging
consistent communications which:
• simplifies component implementations
• reduces the complexity of “glue” logic
• improves system qualities
• applies constraints of what we can (and can’t) do
33
What is REST?

34. © LaunchAny, 2016
• Resources - server-side resources which can be acted
upon
• Each resource has a unique identifier (a URL)
• Actions - the verbs available to use on those resources
• HTTP verbs - GET, PUT, POST, DELETE
• Links – the resources and actions available from your
current location
• Bottom line: REST is a system of patterns with
prescribed ways of composing APIs
34
Resources, Actions, and Links

35. © LaunchAny, 2016
• GET – retrieve a collection or individual resource
• POST – create a new resource or request custom
action
• PUT – update an existing resource or collection, or
create a new resource with a client-assigned ID
• DELETE – delete an existing resource or collection
35
Common HTTP Verbs for REST APIs

36. © LaunchAny, 2016
• 200 - OK - The request has succeeded
• 201 - Created - The request has been fulfilled and resulted in a new resource
being created.
• 202 - Accepted - The request has been accepted for processing, but the
processing has not been completed.
• 204 - No Content - The server has fulfilled the request but does not need to return
a body. This is common for delete operations.
• 400 - Bad Request - The request could not be understood by the server due to
malformed syntax.
• 401 - Unauthorized - The request requires user authentication.
• 403 - Forbidden - The server understood the request, but is refusing to fulfill it.
• 404 - Not Found - The server has not found anything matching the requested URI.
• 500 - Internal Server Error - The server encountered an unexpected condition
which prevented it from fulfilling the request.
36
REST Response Codes

37. © LaunchAny, 2016
• GET /accounts/{id}
• POST /accounts
• PUT /accounts/{id}
• DELETE /accounts/{id}
37
REST Examples

38. Thinking in Resources
38

39. © LaunchAny, 2016
• Any kind of server-side logic or data
• In REST, Nouns over verbs
• Anything we might want to reference
• Typically something representable
• Often high-level business entities
• Might be a database table/view, files, or calculated
result(s)
• We can even model process state
39
What is a Resource?

40. © LaunchAny, 2016
• URL - the globally unique address
• Representation - how to communicate its state
• May be a single resource or a collection of resources
• Examples:
• /users - a collection of resources
• /users/abcdef - an instance in a collection
• /user - a single resource, no collection
40
Elements of a Resource

41. © LaunchAny, 2016
• A resource may have one or more representations
• A representation is any machine-readable format
• Often XML or JSON (or both)
• Can also be HTML (for rendering in a browser)
• Or an image (a photo, chart, graph, etc)
41
Many Representations

42. © LaunchAny, 2016
• Hypermedia connects resources to each other
• It also describes the relationship between them
• Allow client applications to navigate the API
42
What is Hypermedia?

43. © LaunchAny, 2016
Choose your own Adventure

44. <TwilioResponse>!
<Account>!
<Sid>ACxxxx</Sid>!
<FriendlyName>Do you like my friendly name?</FriendlyName>!
<Type>Full</Type>!
<Status>active</Status>!
<DateCreated>Wed, 02 Jan 2013 21:37:41 +0000</DateCreated>!
<DateUpdated>Fri, 04 Jan 2013 01:15:02 +0000</DateUpdated>!
<AuthToken>redacted</AuthToken>!
<Uri>/2010-04-01/Accounts/ACxxxx</Uri>!
<SubresourceUris>!
<Calls>/2010-04-01/Accounts/ACxxxx/Calls</Calls>!
<Conferences>/2010-04-01/Accounts/ACxxxx/Conferences</Conferences>!
<Queues>/2010-04-01/Accounts/ACxxxx/Queues</Queues>!
<Recordings>/2010-04-01/Accounts/ACxxxx/Recordings</Recordings>!
<Sandbox>/2010-04-01/Accounts/ACxxxx/Sandbox</Sandbox>!
<SMSMessages>/2010-04-01/Accounts/ACxxxx/SMS/Messages</SMSMessages>!
</SubresourceUris>!
</Account>!
</TwilioResponse>!
44

45. <TwilioResponse>!
<Account>!
<Sid>ACxxxx</Sid>!
<FriendlyName>Do you like my friendly name?</FriendlyName>!
<Type>Full</Type>!
<Status>active</Status>!
<DateCreated>Wed, 02 Jan 2013 21:37:41 +0000</DateCreated>!
<DateUpdated>Fri, 04 Jan 2013 01:15:02 +0000</DateUpdated>!
<AuthToken>redacted</AuthToken>!
<Uri>/2010-04-01/Accounts/ACxxxx</Uri>!
<SubresourceUris>!
<Calls>/2010-04-01/Accounts/ACxxxx/Calls</Calls>!
<Conferences>/2010-04-01/Accounts/ACxxxx/Conferences</Conferences>!
<Queues>/2010-04-01/Accounts/ACxxxx/Queues</Queues>!
<Recordings>/2010-04-01/Accounts/ACxxxx/Recordings</Recordings>!
<Sandbox>/2010-04-01/Accounts/ACxxxx/Sandbox</Sandbox>!
<SMSMessages>/2010-04-01/Accounts/ACxxxx/SMS/Messages</SMSMessages>!
</SubresourceUris>!
</Account>!
</TwilioResponse>!
45

46. <TwilioResponse>!
<Account>!
<Sid>ACxxxx</Sid>!
<FriendlyName>Do you like my friendly name?</FriendlyName>!
<Type>Full</Type>!
<Status>active</Status>!
<DateCreated>Wed, 02 Jan 2013 21:37:41 +0000</DateCreated>!
<DateUpdated>Fri, 04 Jan 2013 01:15:02 +0000</DateUpdated>!
<AuthToken>redacted</AuthToken>!
<Uri>/2010-04-01/Accounts/ACxxxx</Uri>!
<SubresourceUris>!
<Calls>/2010-04-01/Accounts/ACxxxx/Calls</Calls>!
<Conferences>/2010-04-01/Accounts/ACxxxx/Conferences</Conferences>!
<Queues>/2010-04-01/Accounts/ACxxxx/Queues</Queues>!
<Recordings>/2010-04-01/Accounts/ACxxxx/Recordings</Recordings>!
<Sandbox>/2010-04-01/Accounts/ACxxxx/Sandbox</Sandbox>!
<SMSMessages>/2010-04-01/Accounts/ACxxxx/SMS/Messages</SMSMessages>!
</SubresourceUris>!
</Account>!
</TwilioResponse>!
46

47. {
"_class": "Collection",
"_links": {
"first": {"href": "/v1/audio"},
"item": [
{"href": "/v1/audio/d796f2d0eb72492bb088e0e9fcb1dfa2"},
{"href": "/v1/audio/0fc32337449a4a9d95f78a9a6cc85945"},
{"href": "/v1/audio/fc34f625a12f4e17945c3c027dbaf19e"},
{"href": "/v1/audio/5a7f16a728ea40c4b8179c1b6b1796ec"},
],
"last": {
"href": "/v1/audio?iterator=l1b00000000000000000000000000000000h0"
},
"next": {
"href": "/v1/audio?
iterator=l1adabb46fdba39418390f8c9b2b04a4631h1395421325416"
},
"self": {"href": "/v1/audio"}
},
"limit": 4,
"total": 16
}
47

48. {
"_class": "Collection",
"_links": {
"first": {"href": "/v1/audio"},
"item": [
{"href": "/v1/audio/d796f2d0eb72492bb088e0e9fcb1dfa2"},
{"href": "/v1/audio/0fc32337449a4a9d95f78a9a6cc85945"},
{"href": "/v1/audio/fc34f625a12f4e17945c3c027dbaf19e"},
{"href": "/v1/audio/5a7f16a728ea40c4b8179c1b6b1796ec"},
],
"last": {
"href": "/v1/audio?iterator=l1b00000000000000000000000000000000h0"
},
"next": {
"href": "/v1/audio?
iterator=l1adabb46fdba39418390f8c9b2b04a4631h1395421325416"
},
"self": {"href": "/v1/audio"}
},
"limit": 4,
"total": 16
}
48

49. Modeling APIs
49

50. © LaunchAny, 2016
• Just as a beautiful web design begins from a
wireframe, a great API design begins with an API
model
• Unlike a UI wireframe, API modeling focuses on both
developer and end user goals
• The goal of API modeling is to better understand and
validate the needs of your API
• It should help you figure out actual business
processes beyond Create, Read, Update, Delete
(CRUD) actions
50
Why Model APIs?

51. © LaunchAny, 2016
1. Identify the participants using your API
2. Identify the activities that participants wish to achieve
3. Separate the activities into steps
4. Create a list of API resources and methods
5. Validate Your API
51
5 Steps to API Modeling

52. © LaunchAny, 2016
• List participants that will consume the API directly (or
indirectly)
• e.g. internal developers, external developers, system
admins, users of the system
• Capture a little about them: location, description
52
Step 1: Identify Participants

53. © LaunchAny, 2016 53
Participant Example

54. © LaunchAny, 2016
• An activity is work that produces a desired outcome
and that is accomplished by one or more participants
• An activity might have more than one step – that is OK
• For each activity, you will capture: the name, the
participant(s) involved, and a short description
54
Step 2: Identify Activities

55. © LaunchAny, 2016
Activities Example
55

56. © LaunchAny, 2016
• Activities are composed of steps, with each step being
accomplished by a single participant
• Activity steps may be conducted by more than one
participant, but a single step should only be executed by a
single participant at a time
• Sometimes this step requires a subject matter expert
(SME)
• For each activity step you identify, you will capture: the
activity, the step name, the participant(s) involved, and a
short description
56
Step 3: Break Into Steps

57. © LaunchAny, 2016
Activity Steps Example
57

58. © LaunchAny, 2016
• Start to identify the resources
• You may start to find dependent/nested resources
• Grouping them will make it easier for validating your
API (the next step)
58
Step 4: Create Resource API Definitions

59. © LaunchAny, 2016
• Group like things to a more general concept
• e.g. coffee, tea, water might be products or drinks
• Look for the things, not the bigger concepts
• e.g. /products, not /menu
• Resources can have properties like DB tables have
columns, and can be numbers, strings, lists of values,
etc. so there is no need to make everything a resource
• e.g. size, color, quantity, ingredients, etc.
59
Tips for Finding Resources

60. © LaunchAny, 2016
API Definitions Example
60

61. © LaunchAny, 2016
• Like good a quality assurance (QA) team, your job is to
ensure that your API will meet the requirements of
everyone using it
• Participants are like actors and are the ones that will be
using your API, either directly or indirectly via someone
else’s application
• Activities are like use cases or test cases
61
Step 5: Validate Your API

62. © LaunchAny, 2016
• Break into small groups of 3-5, with at least one analyst
or architect per group (if available)
• Capture: participants, activities, steps, and resources
• For validation, groups will present to another team to
present and review their modeled APIs
• No REST necessary – high level modeling only
62
API Modeling Exercise

63. © LaunchAny, 2016
• Story 1: As a customer, I want to order a coffee so that
the coffee shop can prepare my drink
• Someone in your group can be the expert and scope
the requirements
• Tip: Workflow diagrams help
63
“Getting a cup of coffee”

64. © LaunchAny, 2016
Story 1: As a customer, I want to order a coffee so that the
coffee shop can prepare my drink
• 1. Participants
• 2. Activities
• 3. Activity Steps
• 4. Find Resources
64
Modeling Exercise

65. © LaunchAny, 2016
• Drinks API
• List Drinks
• View Drink Details
• Orders API
• Create Order with drink selection
• Customers API
• Register Customer
• Lookup Customer
Example Coffee Shop API Model

66. From Modeling to API Design
66

67. © LaunchAny, 2016
• Your API model will inform and drive your API design
• The focus shifts from activities to actual REST APIs
that you will build
• Output will result in a high-level API design
• Often accompanied by a prototype
67
From Modeling to Design

68. © LaunchAny, 2016
List Modeled Resources
68

69. © LaunchAny, 2016
Resource Lifecycles
• During modeling, you likely found common verbs
• These verbs often provide clues to the HTTP verb
• Some map directly, some may reveal a bigger concept
and need to be broken down
69

70. © LaunchAny, 2016
Mapping Modeling Verbs
70

71. © LaunchAny, 2016
Example
71

72. © LaunchAny, 2016
• 20x codes indicate success, some with more clarity
(e.g. 201 CREATED vs. 200 OK)
• 40x codes indicate a failure in the request that the
client must fix
• Use the right code for the right reason
• Don’t invent your own!
72
Mapping Response Codes

73. © LaunchAny, 2016
Common Response Codes
73

74. © LaunchAny, 2016
Common Response Codes: GET
74

75. © LaunchAny, 2016
Common Response Codes: POST
75

76. © LaunchAny, 2016
Common Response Codes: PUT
76

77. © LaunchAny, 2016
Common Response Codes: DELETE
77

78. © LaunchAny, 2016
Example
78

79. © LaunchAny, 2016
Documenting
• You need to build documentation anyway
• Writing the documentation first helps solidify purpose
and intent
• Keep it high-level
• Allows for sharing with other teams for feedback
• Use Swagger or similar tool
• Expand the documentation as you implement
79

80. © LaunchAny, 2016
Team Impact of API Design Effort
• Helps the full team understand the API’s purpose
• Helps the full team understand the scope
• Surfaces missing APIs
• Encourages feedback from front-end, other teams
early
• Parallelizes efforts between API developers, API
consumers, QA, etc.
• Prioritizes sprints
80

81. © LaunchAny, 2016
Design Exercise
Using our first two stories that we modeled early, we now
want to apply our design using the following steps:
• 1. List Resources (from Modeling)
• 2. Assign URLs + HTTP Verbs
• 3. Assign HTTP Response Codes
81

82. © LaunchAny, 2016
• Drinks API
• List Drinks
• View Drink Details
• Orders API
• Create Order with drink selection
• Customers API
• Register Customer
• Lookup Customer
Example Coffee Shop API Model

83. © LaunchAny, 2016
Response Status Codes Reference
• 200 - OK
• 201 - Created
• 202 - Accepted
(async)
• 204 - No Content
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
83
❖ 1. List Resources (from Modeling)
❖ 2. Assign URLs + HTTP Verbs
❖ 3. Assign Response Codes

84. © LaunchAny, 2016
Response Status Codes Reference
• 200 - OK
• 201 - Created
• 202 - Accepted
(async)
• 204 - No Content
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
84
❖ 1. List Resources (from Modeling)
❖ 2. Assign URLs + HTTP Verbs
❖ 3. Assign Response Codes
Example API Model:
Drinks API
- List Drinks
- View Drink Details
• Orders API
- Create Order with drink selection

85. © LaunchAny, 2016
• GET /drinks
• GET /drinks/{drinkId}
• POST /orders
• GET /orders/{orderId}
• POST orders/{orderId}/purchase
Example Coffee Shop API

86. © LaunchAny, 2016
• Look for business and technical capabilities
• Use API modeling to map them to APIs
• Apply REST-based API design techniques
• APIs can start as internal initiatives
• Mature into partner or public APIs where appropriate
Wrap-up

87. Thank you!
james@launchany.com
@launchany
87