This workshop with Ronnie Mitra, Layer 7's Principal API Architect, will examine the key foundational elements necessary for a solid API implementation strategy.
Building great APIs is about more than just design; it requires detailed, thoughtful execution. Your API strategy needs to meet the business requirements of your organisation but it must also be flexible enough to meet your developer community’s diverse needs.
12. Web APIs
Language Independent
APIs are constrained by the syntax of the web
Most API Design principles can be applied
Some design principles are unique to Web APIs
49. Innovation
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project
Strategy Implications:
• Design interface for general
use
• Identify success stories
• Eliminate misuse
76. Web API Modern Timeline
2000
Salesforce API
ebay API
2002
Amazon API
2004
Flickr API
2006
Twitter API
Facebook API
Google (Maps)
API
2012
Programmable
web.com has
7144
registered
APIs
Sources: apievangelist.com
programmableweb.com
internetarchive.com
Steve Yegge Rant
oreilly.com
2005
ebay makes
APIs free
2004
First Web 2.0
Conference
2010
Salesforce adds
HTTP API
2008
Programmable
web.com has
1000
registered
APIs
2005
Programmable
web.com
launched
54 APIs
registered.
77. Original APIs are still successful
New business models have emerged
Know your drivers – design accordingly
Summary
78. Building an API Strategy:
Introduction and the Business of APIs
Ronnie Mitra
Principal API Architect - Europe
Layer 7 API Academy
79. Building an API Strategy:
URI Style Design Tips
Ronnie Mitra
Principal API Architect - Europe
Layer 7 API Academy
82. URI Style
• familiar to web developers
• designed for HTTP
• URIs are intuitive
Advantages
83. URI Style
• limited to HTTP methods
• URI design is not standard
• can be ‘chatty’
Trade-offs
84. What is ‘good’ API Design?
• Easy to learn
• Easy to use, even w/o documentation
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to extend
• Appropriate to audience
Joshua Bloch, Principal Software Engineer, Google.
85. Principles of URI Style API Design
• URIs should be intuitive and ‘hackable’
• The interface should adhere to standards
(RFC 2616 and RFC 3986)
• The design should be extendable
86. Naming URIs
• Names matter!
• Establish reserved words and key
words
• Names should be meaningful (to the
application developer)
88. Defining Resources
• Translate interactions into nouns
• Build a resource model
• Avoid RPC/Tunnel style names
• Not everything fits well into the
CRUD + Object space
98. GET
• Retrieve a representation
• ‘safe’ method according to RFC
• no user-requested side effects
• won’t impact data
• ‘Conditional GET’ is supported with
caching
• Don’t abuse for non-read operations
99. PUT
• Write a representation
• Store the entity (full replacement)
• Idempotent
• Example:
PUT /myapi/messages/14
{Message}
100. Idempotence
No side-effects on identical calls
PUT /myapi/messages/14
Result: Message Replaced
PUT /myapi/messages/14
Result: Message Replaced
101. Full Replacement
PUT /myapi/messages/14
{ “title”: “Welcome”}
{
“id”:”14”
“title”:”Wlecome”
“author”:”Ronnie”
“body”: “Hi Glen, welcome to the team!”
}
On the Server:
{
“title”:”Wlecome”
}
102. Why not use PUT for partial update?
• Breaks HTTP specification
• No defined semantic – can produce
unexpected results from a dev
perspective
103. PATCH (Partial Update)
• RFC 5789 (HTTP Patch)
• Partially update an identified
resource with the supplied entity
• Example:
PATCH /myapi/message/14
{Partial Message}
111. POST
• Write/Process an entity
• Accept entity as sub-ordinate
resource
• Not Idempotent
• No identifier specified (factory
pattern):
POST /myapi/messages
114. Method Tunneling
• Older platforms may not support all
verbs
• Need to resort to embedding the
verb in a header or parameter
• Example:
GET myapi/shops?method=POST
• Avoid doing this
115. Representations
Expose object properties that are
relevant to the developer
Embed child objects and properties,
but need to decide on granularity
Design structures that are extensible –
be careful when implementing
schema
119. Retrieve a Collection of Data
• Example: “Retrieve all store
locations”
• GET /shops
120. Retrieve a Filtered Collection of Data
• Filter by requesting children
• GET /shops/london
• GET /shops/amsterdam
• Limited to objects and sub-objects
• Difficult to retrieve unions/joins of data
121. Retrieve a Filtered Collection of Data
• Example: “Retrieve all store locations in
London”
• Use query parameter from URI spec
• GET /shops?location=London
• GET /shops?location=London,Amsterdam
• GET /shops?location=London&sort=distance
122. Complex Queries
“retrieve all shops within a radius of 10 km
from a specific location that are open
within specified hours and sell specific
phones, devices and account plans”
GET
/shops?radius=10&location=8882,28832&open_time=38882034
&close_time=23882343&phones=iphone,blackberry,samsung&
plans=monthly_3GB,monthly_4GB,pay_go_2GB
123. Complex Queries
URI space may be limited
Long queries can become difficult to
manage
Use POST on an operator resource:
POST /shopsquery
{
“radius” : “10”, “location” : “388203,838200”,
“phones” : [“blackberry”, “iphone”]
}
128. Pagination
• use links to navigate
{“href”:“/api/resource?offset=11&count=
20”,
“rel”:“next”}
• client doesn’t have to calculate
location
• easier to navigate through pages
129. Pagination
• use defaults to reduce ‘friction’
• reduces learning curve for new
developers
/api/resource?offset=10&count=20
/api/resource
/api/resource?offset=10&count=10
136. Implementing Versioning
• myapi/v1/path
• Try to extend instead of version
• Don’t break what is already there
• Clients should ignore what they
don’t understand
• Introduce breaking changes if you
want to drive developers away.
140. XML vs. JSON?
• Not very different
• ‘<‘ vs. ‘{‘
• Similar performance overhead
• Most clients support both (XML
more widely supported)
• What do your developer’s prefer?
141. HTML
• Hypermedia content type
• Web Form: application/x-www-form-
urlencoded
• Useful for simple name/value pair
input
• Easy for developers to implement
143. Status Codes
• 1xx: Informational
• 2xx: Success
• 3xx: Redirection
• 4xx: Client Error
• 5xx: Server Error
144. Status Codes
• You MUST use the correct category
• The second part of the code (xx) is
largely informational, but still
important
• Reason phrases can be customized
160. Adaptive Responses
• Provide responses that are the best
fit for the calling application
•Examples:
• Reduced granularity
• Different defaults
• UI Driven
161. URI Design Summary
• Some standards, but lots of choices
• Design with developer in mind
• Consistency and structure are
important
162. Building an API Strategy:
URI Style Design Tips
Ronnie Mitra
Principal API Architect - Europe
Layer 7 API Academy
163. Building an API Strategy:
The Developer Experience
Ronnie Mitra
Principal API Architect - Europe
Layer 7 API Academy
218. Security
Security can hurt Usability
But… security can also improve the
overall experience!
We need to think about the system as a
whole
219. Complexity
• Sometimes complexity is necessary –
that is ok
• Enough features to meet
requirements
• Don’t hurt the DX – use structure
and modularity
239. Map Interactions to an API Design
Which style?
Which formats?
How do we translate interactions?
240. Prototype
Don’t bind to real data or backend
Use something lightweight and easy
to change
Do this early
241. Practical Prototyping
Write simple code or script in a language
that is easy for you to implement.
var express = require('express'),
app = express();
var port = 8080;
app.listen(port);
app.get("/tasks", function(req, res) {
res.status(200).send(‘<response>
<tasks>
<task>
<name>Pick up Kai</name>
<priority>1</priority>
</tasks>
</response>’);
}
243. Practical Prototyping
Apply minimal security
Try writing throwaway client code
Ask target developers to write code and
use the API
Make quick changes and try it again
244. Focus on the interactions that take
place, rather than the interfaces
we expose
269. Caching Layer
Caching happens EVERYWHERE
HTTP supports Expiration Model and Validation Model Caching
Expiration Model
- Expires
- Cache-Control: max-age
Validation Model
- Last-Modified
- Etag, If-Match
Be prepared to support caching for both client and server
Squid, Varnish, Nginx, MemCacheD, NSURLConnection etc.
279. Nuts and Bolts of API Management
Developer Registration
Access Control
API Explorer
API Documentation
Social Engagement
Tracking and Reporting
290. Injection Attacks
Utilizing input parameters to inject data that compromises
the security of the targeted system.
Examples:
- SQL Injection
- Command Injection
- Code Injection
- Argument Injection
291. API Attack Example:
SQL Injection Attacks: APIs
GET http://host.com/aresource?token=
%E2%80%98or%20%E2%80%981%3D1
GET http://host.com/aresource?token=‘ or ‘1=1
select * from tokens where token = ‘’ or ‘1=1’;
292. APIs May Be A Direct Conduit
292
HTTP
Server
App
Server
Database
App
Objects
Often:
• Self-documenting
• Closely mapped to object space
293. Denial Of Service Attacks
An attack which has the objective of making a service
unavailable to all users
Examples:
- XML/JSON parser attacks
- Jumbo messages
- Server overload
294. Overflow Attack
Intentionally sending too much data in order to exploit a
target systems by exceeding expected boundaries.
Examples:
Buffer Overflow
Cash Overflow
295. Cross Site Scripting (XSS) Attack
Embedding code within a server that will be
transmitted to users.
296. XSS API Example
296
Attacker
Web App Server
(browser+APIs)
Victim: Web
Browser
Client
<SCRIPT …>
1. API injects
script in
3. Browser loads
content with
embedded script
2. Server fails to
perform FIEO: Filter
Input, Escape Output
API
298. OWASP Top Ten (2010 Edition)
Source: http://www.owasp.org/index.php/Top_10
299. Impersonating a registered application in order to access
an API resource.
Examples:
- Guessing application ID by brute force
- Retrieving application ID by sniffing traffic
- Cracking application to retrieve application ID
App Spoofing
300. how can I protect identity on a mobile device?
326. Authorization Code Grant
326
Client Application
Resource Owner
Using
Application
Resource Server
I Wish I could access
my resources through
this application…
327. Authorization Code Grant
327
Client Application
Resource Owner
Using
Application
Resource Server
…but I don’t trust this
app enough to give it
my credentials.
329. Authorization Code Grant
Initiation
329
Client Application
Resource Owner Authorization Server
Resource Server
User Agent
Issue GET
request via
User-Agent
response_type
client_id
redirect_uri
scope
state
330. OAuth 2 Authorization Request
response_type – indicates grant type
client_id –application identifier
redirect_uri (optional) – address which the UA can use to respond to client
scope (optional) – space delimitted string: what the client wants to do
state (optional)– opaque string used to defeat CSRF attacks
Sample Authorization GET URL:
https://azserver/oauth2/authorize?response_type=code&client_id=my_id&state=state&r
edirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback
331. Authorization Code Grant
Resource Owner Authentication
331
Client Application
Resource Owner Authorization Server
Resource Server
User Agent
Send
User
Authentication
Form
?
Authenticate
333. Authorization Code Grant
Receipt of Authorization Code
333
Client Application
Resource Owner Authorization Server
Resource Server
User Agent
Redirect
User-Agent
Client
Application
! Redirected
To
Client
Application
code
state
302
334. Authorization Code Grant
Access Token Request
334
Client Application
Resource Owner Authorization Server
Resource Server
Request
Access
Token
Return
Access
Token
and Optional
Refresh Token
grant_type
code
redirect_uri
client_id
200
AZ Code
AZ Code
335. Authorization Code Grant
Access Protected Resource
335
Client Application
Resource Owner Authorization Server
Resource Server
Request
Resource
Using
Application
Return
Resource
200
336. Authorization Code Grant - Summary
Most Complex of OAuth 2 Grant Types
Provides full OAuth 2 capability
337. 2 vs. 3 Legged Spectrum
337
Three
legged
Two
legged
339. OAuth 2 Challenges
New attack surfaces
Flexible, but complex for API publishers to implement
Utilizes redirection URIs (should be validated with strong rules)
Poor implementations will be exposed (see Facebook)
Not a solution to user authentication
340.
341. OpenID Connect
Identity Access and Authentication (when combined with Open ID)
Built on top of OAuth 2
Not tied to any single vendor or identity provider
342. Open ID, Open ID Connect and OAuth 2
OAuth 2 allows an end-user to grant an application access to protected resources
However:
- The authorization server must still authenticate the end-user
- The client application is unable to determine information about the end-user
Client Application
Resource Owner Authorization Server
User Agent
Send
User
Authentication
Form
?
Authenticate
343. OpenID Authentication can help the server authenticate the end-user
OpenID Connect provides a mechanism for the application to learn about the end-
user
Open ID, Open ID Connect and OAuth 2
Client Application
Resource Owner Authorization Server
User Agent
Send
OpenID
Authentication
Form
Authenticate
Retrieve User
Information
OpenID
Resource
Server