Mais conteúdo relacionado Semelhante a James Higginbotham - API Design (20) Mais de John Zozzaro (11) 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
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
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!
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?
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)
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
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?
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
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
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
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
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
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
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
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
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
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
