1.
API Workshop
Ronnie Mitra
Principal API Architect - Europe
Layer 7 API Academy

2.
API Management
virtual cloudon-premise

3.
API Academy
Mike Amundsen Ronnie Mitra

4.
www.apiacademy.co

5.
Business of APIs
API Styles
Usability
Security
API Architecture
SOA Governance

6.
What are
Web APIs?

7.
Connecting things

8.
Connecting computer programs

9.
API
All programmers are API designers
Connections between modules
Language Dependant
APIs are constrained by the syntax of the
language

10.
… over the web

11.
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

12.
Web of
Documents
Web of
Apps
Web of
Services
Web of
Things

13.
The web is ubiquitous
And universally accessible

14.
Publishers retain control

15.
We are surrounded by Web APIs

16.
Did you check the weather today?

17.
Private or Closed APIs

18.
Acme Corp.
API
Acme Corp.
App

19.
Public or Open APIs

20.
Acme Corp.
API
Third Party
App

21.
Priority:
Lower Cost
Priority:
Increased Adoption

22.
Business of APIs

23.
why build an API?

24.
Innovation
Consumer Reach
Revenue Source
Marketing
Integration
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

25.
Innovation
Consumer Reach
Revenue Source
Marketing
Integration
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

26.
Revenue Source

27.
Revenue Source
http://www.flickr.com/photos/inside-south-africa/485356704
£0.10 per API Call

28.
Revenue Source
1000 calls/month
5000 calls/month

29.
Revenue Source
500 calls/month
1000 calls/month
5000 calls/month

30.
Revenue Source
Is your content worth paying for?

31.
Innovation
Consumer Reach
Revenue Source
Marketing
Integration
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

32.
Consumer Reach

33.
Consumer Reach

34.
Head Long Tail
Consumer Reach

35.
Innovation
Consumer Reach
Revenue Source
Marketing
Integration
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

36.
Marketing
Affiliate Programs
Sometimes you pay the developer.

37.
Marketing
Draw new visitors in.

38.
Marketing

39.
Innovation
Consumer Reach
Revenue Source
Marketing
Integration
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

40.
Innovation
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project
Innovation from within

41.
Innovation
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project
Innovation outside your borders

42.
Innovation
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project
When does innovation happen?

43.
Innovation
Consumer Reach
Revenue Source
Marketing
Integration
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

44.
Integration
Business driven integration
Regulatory driven integration

45.
Observational Learning:
Five Short Stories of Public APIs

46.
2000 – ebay

47.
Started with a paid developer program in 2000
Made it free in 2005

48.
Consumer Reach
Marketing

49.
Large developer eco-system
Large app eco-system

50.
25% of eBay listings come from their API!

51.
salesforce
2000 – salesforce

52.
Integration
Revenue Source

53.
API as a cloud enabler

54.
2004 – Flickr

55.
web 2.0 generation

56.
Consumer Reach
Marketing

57.
The rise of self-service
Announced 6 billion photos in August 2011

58.
2006 – Amazon Web Services

59.
Started as an online book shop…
Became a department store…
now?

60.
Jeff Bezos
Connect everything
http://www.flickr.com/photos/zippy/2430495092

61.
2004:
Hey, why don’t we sell this?

62.
Revenue Source

63.
Estimated revenue:
$1.5B in 2012
http://wikibon.org/wiki/v/Cloud_Computing_2013%3A_The_Amazon_Gorilla_Invades_the_Enterprise

64.
Twilio or stripe
2007 - Twillio

65.
Revenue Source

66.
The API is the business

67.
100,000 developer milestone in 2012

68.
Original APIs are still successful
New business models have emerged
Different drivers have influenced API design
Summary

69.
Why make an API Public?

70.
Unlock new markets
External innovation
Drive revenue
“Free” development
Crowdbased asset development

71.
Promote Mutual Gain
(Symbiosis)

72.
http://upload.wikimedia.org/wikipedia/commons/f/ff/Aedes_albopictus_cdc.jpg

73.
http://commons.wikimedia.org/wiki/File:Arothron_hispidus_is_being_cleaned_by_Hawaiian_cleaner_wrasses,_Labroides_phthirophagus_1.jpg

74.
Don’t forget:
More developers = Higher Costs

75.
Bandwidth
Technical Support
Processing and Storage
?

76.
Documentation
Tools
Evangelists and communities
Supporting Developers
Connector designed by R Chow from The Noun Project
Notepad designed by Luis Prado from The Noun Project

77.
API Management

78.
To ensure failure, make your API:
• difficult to understand
• dangerous to use (unsafe)
• unreliable and unstable
• opaque (provides no visibility)

79.
API management helps us:
• Drive adoption
• Lower costs
• Keep existing users
• Reduce friction

80.
Innovation
Consumer Reach
Revenue Source
Marketing
Integration
Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

81.
Without API management an API is naked.

82.
Business of APIs Summary
• Understand the business motivation
• Choose a style that fits your constraints
and goals

83.
API Styles

84.
What does a Web API look like?

85.
Web APIs
HTTP

86.
Architectural Styles

87.
Tunnel Style
URI Style
Hypermedia Style
Event Driven Style

88.
Tunnel Style
Example: SOAP
• transport agnostic
• operation based
• binding documents (WSDL)

89.
Tunnel Style
<RetrieveStudentRecords>
<StudentId>1213</StudentId>
</RetrieveStudentRecords>

90.
Tunnel Style
• lots of tooling
• not restricted to HTTP
• RPC
Advantages

91.
Tunnel Style
• inefficient for HTTP
• increased learning curve
• lack of tooling in mobile
Trade-offs

92.
URI Style
GET
PUT
POST
DELETE
+ URI

93.
URI Style
GET /students/1232

94.
URI Style
• familiar to web developers
• designed for HTTP
• URIs are intuitive
Advantages

95.
URI Style
• limited to four methods
• URI design is not standard
• can be ‘chatty’
Trade-offs

96.
Hypermedia Style

97.
Hypermedia Style
• links
• templated input (forms)
• task based

98.
{
links: [
link {href: ‘…’ rel: ‘list’},
link {href: ‘…’ rel: ‘add’}
]
collection: [
{link: {rel:'complete',href:‘…'},
id:42,
text:‘Record 42'
}
]
}

99.
Hypermedia Style
• designed for HTTP
• long lasting
• no URI construction
Advantages

100.
Hypermedia Style
• leading-edge
• requires ‘smarter’ apps
• less familiar to developers
Trade-offs

101.
Event Driven Style
Example: WebSockets
• event based communication
• server initiated events
• full-duplex (websocket)

102.
Event Driven Style
• less overhead
• better performance
Advantages

103.
Event Driven Style
• not HTTP-based
• resource intensive connections
• inefficient for request-reply
Trade-offs

104.
API Styles Summary
• Web API != standard
• Four popular styles: Tunnel, URI,
Hypermedia, Event
• Choose a style that fits your constraints
and goals

105.
Usability

106.
Interaction
Design

107.
Usability
Human-Computer-Interaction
User Experience Design
Goal Oriented Design

108.
A user-centric view of design.

109.
http://www.flickr.com/photos/58754750@N08/5541472392/

110.
Well designed products are easier
to use.

111.
Good design matters for Web APIs
too.

112.
“Frictionless” integration
High rates of adoption
Low cost integration
We want:

113.
Focus on the developer experience
(dx)

114.
Portal
API

115.
Why is this difficult?

116.
Reason #1
We project our own perspective.

117.
Your code is not your API.
Your data model is not your API.

118.
Reason #2
We project our own biases.

119.
Never use SOAP?
Why?

120.
Consider keyboards…

121.
http://www.flickr.com/photos/yvettemn/139890573/

122.
http://www.flickr.com/photos/jonathanpberger/7126054997/

123.
http://www.flickr.com/photos/novemberborn/286773981/

124.
It doesn’t matter that you don’t like
SOAP.

125.
What matters is what your
developer base thinks!

126.
Reason #3
We make bad assumptions.

127.
API publishers are also developers.

128.
Reason #4
We lack the time, money or
incentive for good design

129.
“Best practices”, patterns and
standards become shortcuts

130.
Am I RESTfull enough?

131.
So, how can we do better?

132.
Developer-centric design requires
effort and diligence.

133.
Is the answer an SDK?

134.
An SDK shifts the design effort but
does not resolve the usability
challenge

135.
Design with the developer in mind.

136.
Ask them.

137.
• Interviews
• Surveys
• Listen (blogs, presentations,
tweets)

138.
"If I had asked people what they
wanted, they would have said
faster horses.“ – Henry Ford?

139.
• Observe
• Prototype
• Historical Data

140.
Consider all aspects of the DX:
Registration
Security
Troubleshooting
Learning
Interface Style

141.
Registration
Lazy Registration
Social Integration
Personalization

142.
Development Activity Cycle
1. Learn
2. Code
3. Implement
4. Test
5. Fix

143.
Portal
API
Learn
Code
Test

144.
API
Learn
Test

145.
API explorers and “live
documentation” can shorten the
gap between visibility and
feedback.

146.
1. Identify a Target Audience
2. Learn about the audience
3. Make API design choices that
are developer-centric
4. Prototype and get feedback
5. Iterate
How?

147.
Focus on the interactions that take
place, rather than the interfaces
we expose

148.
Great API design can thrive in a
developer-centric environment

149.
Usability Summary
• Focus on the developer
• Start by thinking in terms of interactions
• Effective for public and private APIs

150.
Securing APIs

151.
OWASP Top Ten (2010 Edition)
Source: http://www.owasp.org/index.php/Top_10

152.
The primary API management
challenge:
Balancing
Control and Accessibility

153.
Identity
Authentication
Authorization
Availability
Integrity
Privacy

154.
TLS
OAuth 2
Open ID Connect

155.
OAuth provides a
Delegated Authorization Framework

156.
An imperfect analogy….

157.
http://www.flickr.com/photos/drewleavy/5587005480

158.
http://www.flickr.com/photos/24oranges/5791460046/

159.
http://www.flickr.com/photos/grumbler/571106054/
http://www.flickr.com/photos/roboppy/238406811/
Your Money
This Shop Needs Your Money
You need to grant access
to your money

160.
http://www.flickr.com/photos/drewleavy/5587005480
I won’t tell.
I promise!

161.
www.flickr.com/photos/auntiep/255249516

162.
Granting access to someone to act
on your behalf.

163.
Your resources
This app needs to act on your behalf
You need to grant access
to your resources

164.
Your google+ data
This app needs to access your
Google+ data
You need to grant access
to your resources

165.
Hi Google.
I’d like to have
access to a
user’s data.

166.
Hang on,
let me
ask…

167.
He said yes.
Here is your
access
code.

168.
Proprietary authorization implementations
OAuth (2007)
OWrap
OAuth 2
History of OAuth

169.
OAuth 2 Grant Types
 Grant Types:
- Authorization Code
- Implicit
- Resource Owner Password Credentials
- Client Credentials

170.
OAuth 2 Challenges
It is a framework

171.
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

172.
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

173.
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

174.
 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

175.
Security Summary
• Keep focus on usability
• Utilize standards like OAuth and TLS
• Danger in poor implementations

176.
Designing an API Architecture

177.
http://www.flickr.com/photos/naomi_pincher/3306312873/
Layered Pattern

178.
Representation Layer

179.
Component != Connector

180.
Component
Database
File System
Message Queue
Transaction Manager
Source Code

181.
Components Are Private

182.
Connector
Web Server
Browser Agent
Proxy Server
Shared Cache

183.
Connectors Are Public

184.
Client Server
Connectors
Components
The Web

185.
The Treachery of Images - René Magritte

186.
Representation Layer
 Representation happens in the Connector
 HTTP supports content negotiation
- Accept
- Content-Type
 Differing clients (user-agents) === differing representations
- Desktop
- Browser
- Tablet
- Smartphone
 Be prepared to support multiple representations

187.
• Data and Interface Transformation
• Focus on the interface (usability)
Representation
SOAP
Legacy

188.
Security Layer

189.
Security implementations are difficult:
• Mistakes are costly
• Hard to understand specifications
• Performance can suffer

190.
Don’t implement security in the API
Enforce security at the edge

191.
Caching Layer

192.
Caching Layer

193.
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.

194.
Orchestration Layer

195.
• Chaining multiple calls
• Aggregating and enriching data
• ‘mashup’ external data with internal data
Orchestration:

196.
Gateway Pattern
 Abstraction of multiple interfaces
 In Software Engineering: Façade Pattern
 Benefits:
- Deliver a consistent experience
- Centralize API functionality
http://martinfowler.com/eaaCatalog/gateway.html

197.
API Gateway
Gateway
API
API

198.
Restrict Access
Improve Performance
Focus on Usability

199.
The gateway doesn’t solve all our problems

200.
API portals
Portal

201.
API Management
Portal
Gateway
API
API

202.
We also apply this philosophy behind the firewall.

203.
Architecture Summary
• Use a layered architecture
• Deploy a gateway for runtime
• Deploy a portal for developers

204.
SOA Governance vs. API Management

205.
Web APIs: New and Exciting!
http://www.flickr.com/photos/every1knows/4191971139

206.
“Web APIs? I’ve been doing that for years.”
Image courtesy of http://www.flickr.com/photos/en321/3902138429/

207.
Web APIs offer us a new perspective
http://www.flickr.com/photos/mugley/4407790613

208.
The Modern Philosophy of the Web API:
• self service
• lower barriers and lower costs
• developer-centric

209.
All hail the developer kings!

210.
SOA Governance
Enforce access control
Promote service usage
Provide service discovery documents
Provide service usage visibility

211.
API Management
Enforce access control
Promote API usage
Provide API documentation
Provide API usage visibility

212.
SOA Governance
How do we make sure that these
services are used properly?

213.
API Management
How do we get people to use our API
without falling over?

214.
Controlled versus Organic

215.
Representing organizations is useful
Complexity sucks
Focus on the user
What can we learn from SOA
Governance?

216.
Web APIs are acting on a planetary scale
Service
Service
Service
ESB
ISB
API
API
API

217.
SOA Governance Summary
• Different but converging
• Developer based perspective
• Based on success

218.
API Workshop
Ronnie Mitra
Principal API Architect - Europe
Layer 7 API Academy