The document presents best practices for API management by WSO2, covering key topics such as the importance of security, versioning, and monitoring. It outlines the requirements for a successful API management platform, including user management, API publishing, and analytics integration. The presentation also emphasizes the need for documentation and support for developers to foster API adoption and ensure secure and efficient service delivery.

1. Last Updated: March 2014
Director,
Product
Management,
WSO2
Isabelle
Mauny
Best
Prac1ces
for
API
Management
Thursday, March 27, 14

2. About
the
speaker...
๏ French
na)ve
๏ Living
in
Spain
๏ Works
mostly
with
Sri
Lanka
๏ 18
years
of
IBM,
4
years
in
startups
๏ Managing
the
overall
WSO2
porDolio
๏ Linux
command
line
user
2
Thursday, March 27, 14

3. Who
is
WSO2
?
๏ Open
Source
Middleware
Pla2orm
Provider
๏ Apache
2.0
License
๏ Provides
Integra?on,
API
Management
and
Mobile
enterprise
management
products
๏ Main
contributor
to
Apache
Stratos
PaaS
๏ Creators
of
DevOps
“AppFactory”
cloud
solu?on
3
Thursday, March 27, 14

4. Business
Model
4
Thursday, March 27, 14

5. Define
a
Business
Model
5
๏ What
are
the
business
goals
?
๏ Enable
3rd-­‐party
Mobile
Apps
development
?
๏ Increase
brand
recogni)on
?
๏ Open
new
revenue
channels
?
๏ Define
Mone)za)on
model
๏ Free
?
๏ Pay
per
usage
?
๏ Free
APIs,
but
paid
via
Ads
Thursday, March 27, 14

6. Development
6
Thursday, March 27, 14

7. ๏ Service
deals
with
implementa)on
๏ API
deals
with
subscrip)on
(consumer)
๏ Two
very
dis)nct
life
cycles
!
๏ You
don’t
need
the
service
to
create
the
API...
Services
and
APIs
7
Thursday, March 27, 14

8. Building
a
Managed
API
๏ Crea)ng
APIs
(interface,
docs,
samples,etc.)
๏ Adver)sing
APIs
๏ Making
APIs
subscribe-­‐able
by
consumers
๏ Associa)ng
SLAs
๏ Securing
APIs
๏ Mone)za)on
and
Analy)cs
8
Thursday, March 27, 14

9. API
Security
9
Thursday, March 27, 14

10. API
Security
๏ Security
is
not
an
aYer
thought
!
๏ APIs
are
part
of
a
much
larger
enterprise
picture
๏ How
will
consumers
request
an
access
token
?
๏ Using
a
SAML
2.0
asser)on
?
๏ Using
client_creden)als
?
๏ Using
userid/password
?
๏ Make
sure
you
document
thoroughly
how
developers
need
to
manage
tokens:
๏ Tokens
are
like
passwords!
๏ Always
use
SSL
for
token
transporta)on
!
๏ Use
Domain
restric)ons
(WSO2
API
Manager)
10
Thursday, March 27, 14

11. Fine-­‐grained
access
to
APIs
๏ OAuth2
is
all
about
access
control:
a
token
is
associated
to
a
scope.
๏ XACML
(eXtensible
Access
Control
Markup
Language)
is
the
de-­‐
facto
standard
for
fine-­‐grained
access
control.
๏ OAuth
scope
can
be
represented
in
XACML
policies
๏ Provides
fine
grain
control
over
what
a
user/applica?on
can
do
(
i.e.
you
can
call
GET
but
not
POST
on
an
API)
11
Thursday, March 27, 14

12. Passing
Auth
Informa6on
to
back-­‐end
services
๏ Using
JSON
Web
Tokens
(JWT)
๏ Lightweight
๏ Can
be
signed
๏ Easy
to
parse
and
consume
๏ Standard
API Gateway
API Management
Layer
Services Layer
Internal and External Applications
OAuth 2 Access
Token
JSON Web
Token
12
Thursday, March 27, 14

13. Token
Format
๏ JWT
Structure
{token
info}.{claims
list}.{signature}
๏ Base-­‐64
Encoded
13
Thursday, March 27, 14

14. What
are
Claims
?
๏ Claims
are
a
set
of
aTributes
about
a
user,
mapped
to
the
underlying
user
store.
๏ A
set
of
claims
is
called
a
dialect
14
Thursday, March 27, 14

15. Publishing
15
Thursday, March 27, 14

16. Choosing
an
API
Management
Pla=orm
16
๏ What
the
pla2orm
must
do,
at
a
minimum:
๏ Users
Management
(self-­‐sign
up,
profile
management)
๏ API
Publica?on
/
API
Store
๏ API
Security
๏ Sta?s?cs
๏ SLA
control
๏ ThroTling
/
Rate
Limi?ng
๏ API
Versioning
๏ Mone?za?on/Billing
๏ and
more
!
๏ You
could
build
all
of
this
yourself,
but...
Thursday, March 27, 14

17. Need
for
API
Versioning
๏ Need
to
support
API
evolu)on
๏ While
Maintaining
๏ Backward
compa)bility
-­‐>
Func)onality
๏ Rates/Throhling
agreements
๏ Different
versioning
mechanisms
17
Thursday, March 27, 14

18. API
Versioning
Strategies
๏ Version
as
a
query
parameter
๏ Ne=lix
-­‐
hTp://api.ne2lix.com/catalog/?tles/series/70023522?v=1.5
๏ Google
Data
API
-­‐
“GData-­‐Version:
X.0″₺
or
“v=X.0″₺
๏ Version
as
part
of
URI
๏ Salesforce
-­‐
hTps://na1.salesforce.com/services/data/v20.0/sobjects/Account/
๏ TwiDer
-­‐
hTps://api.twiTer.com/1.1/statuses/men?ons_?meline.json
๏ Version
as
a
date
in
URI
๏ Twilio
-­‐
/2010-­‐04-­‐01/Accounts/{AccountSid}/Calls
๏ hTp://www.twilio.com/docs/api/rest/making-­‐calls
๏ Version
as
a
๏ Custom
HTTP
Header
๏ Accept
Header
18
Thursday, March 27, 14

19. API
Lifecycle
๏ An
API
can
pass
through
mul)ple
states
๏ For
example:
๏ CREATED
๏ PUBLISHED
๏ DEPRECATED
๏ RETIRED
๏ BLOCKED
๏ Should
integrate
with
complete
governance
lifecycle
19
Thursday, March 27, 14

20. Show
some
developer’s
love
:)
20
๏ Docs
,
docs
and
more
docs
๏ API
Samples,
in
many
languages
๏ Embedded
Tes)ng
๏ Provide
sandbox
and
produc)on
run)mes
๏ SDK
๏ Wraps
API
access,
including
security
Thursday, March 27, 14

21. Deployment
21
Thursday, March 27, 14

22. Gateway
vs.
ESB
22
๏ Oh,
but
I
already
have
an
ESB
!
Why
do
I
need
a
gateway
?
๏ API
Gateway
vs.
Media)on
Layer
(ESB)
๏ Gateway
=
light
ESB
?
๏ Think
ESB
as
an
architecture
pahern,
not
a
product!
Thursday, March 27, 14

23. Generic
Facade
PaZern
๏ Pros
๏ No
addi)onal
hop
in
the
network
๏ Single
Server
to
be
managed
๏ More
suited
for
internal
deployments
๏ Cons
๏ Complexity
of
integra)on
at
edge
of
network
๏ API
Management
layer
can’t
really
scale
independently
๏ Not
appropriate
for
DMZ
deployments
(direct
access
to
backend
services)
23
API Gateway
API Management
Layer
Services Layer
Internal and External Applications
Thursday, March 27, 14

24. Separated
Facade
&
Mediaon
๏ API
Gateway
Layer
acts
as
simple
reverse
proxy,
enforcing
basic
policies
๏ Clear
separa?on
of
concern
between
layers
๏ Media?on
layer
and
API
management
layer
scale
independently
๏ Specific
security
checks/protec?on
at
edge
of
the
network
๏ Provides
protocol
transforma?on
to
the
edge
of
the
network
24
API Gateway
API Management
Layer
Services Layer
Internal and External
Applications
API Gateway
API Management
Layer
Services LayerMediation
Layer
Services
Composition
Services
Orchestration
Thursday, March 27, 14

25. Specific
WSO2
Soluon
๏ Our
API
gateway
is
actually
a
full-­‐blown
ESB
under
the
hood,
constrained
at
UI
level.
๏ You
can
install
the
missing
ESB
features
on
top
of
API
manager
and
combine
both
architecture
layers
into
a
single
run)me!
๏ Makes
the
choice
a
deployment
one.
25
Thursday, March 27, 14

26. Typical
Deployment
26
Web Tier
BPS
Server
API GatewayLoad
balancer
API Gateway
External APIs Tier Orchestration Layer
External Web
Application
External Mobile
Application
Token Validation, Policy Decision
Point, Users Store Management
ESB
Server
Data Access Layer
ESB
BPM
Data Services
Server
Identity Server
Messaging Layer
Message Broker
Server
API Gateway
Load
balancer
API Gateway
Internal APIs Tier
Identity Server
Thursday, March 27, 14

27. Users
Store
๏ Separate
admins
/
corporate
users
from
the
developers
users’s
store
(created
via
self-­‐sign
up)
27
Thursday, March 27, 14

28. You
can’t
manage
what
you
can’t
measure.
28
Thursday, March 27, 14

29. Why
Analy6cs
and
API
Management
are
important
together?
๏ Build
confidence
in
the
API
model
๏ Understand
your
customer
๏ Not
just
the
developer
but
also
the
end-­‐user
๏ Help
manage
services
and
versions
๏ Understand
when
deprecated
services
can
be
re?red
๏ Plan
beTer
๏ Monitor
the
growth
of
aggregated
API
traffic
๏ Monitor
the
growth
of
specific
apps
๏ Even
if
you’re
not
going
to
put
analy?cs
in
place,
make
sure
you
capture
all
events
right
from
beginning
of
project.
29
Thursday, March 27, 14

30. Analycs
101:
Aggregaon
• How
to
collect
data
efficiently
• How
to
store
data
effec)vely
• Choose
which
data
to
capture
30
Thursday, March 27, 14

31. Analycs
101
:
Analysis
• Data
opera)ons
• Defining
KPIs
and
analy)cs
• Opera)ng
on
large
amounts
of
historical
or
current
data
• Crea)ng
intelligence
31
Thursday, March 27, 14

32. Analycs
101
:
Presentaon
• Visualiza)on
• Dashboards
• Reports
32
Thursday, March 27, 14

33. Events Collector
EVENTS
DATASTORE
3rd party
Products
WRITES EVENTS
Report Generator
CEP Engine
FEEDS EVENTS
GENERATE NEW EVENTS
Analytics Engine
Real Time Decision
Engine
DEPLOYS LOGIC
ANALYTICS
DATASTORE
User Engagement Server
33
Monitor
And
Analyze
๏ Take
decisions
in
real
?me
through
Complex
Event
Processing
๏ Create
dashboards
for
both
technical
and
business
monitoring
Thursday, March 27, 14

34. Detecng
Usage
PaZerns
๏ My
API
customer
is
trying
to
steal
my
business
:
let’s
block
them.
๏ A
customer
is
at
80%
of
API
plan
:
let’s
warn
them
๏ A
customer
is
systema)cally
at
120%
of
the
plan
:
propose
an
upgrade
to
the
premium
plan
34
Thursday, March 27, 14

35. Demo
35
Thursday, March 27, 14

36. Demo
Setup
36
Web Tier
API Gateway
APIs tier
Mediation Layer
External Web
Application
Token Validation, Policy Decision Point,
IdentityProvider, Users Store Manager
ESB
Server
Services Layer
ESB
Application
Server
Messaging Layer
Message Broker
Server
Identity Server
Reporting, Logging, Operational Analysis
BAM CEP
Thursday, March 27, 14

37. References
๏ Building
an
ecosystem
for
API
Security
(White
Paper)
๏ hhp://wso2.com/whitepapers/wso2-­‐whitepaper-­‐building-­‐an-­‐ecosystem-­‐for-­‐api-­‐
security/
๏ API
Facade
Pahern
(Webinar)
๏ hhp://wso2.com/library/webinars/2014/01/implemen)ng-­‐api-­‐facade-­‐using-­‐
wso2-­‐api-­‐management-­‐plaDorm/
๏ API
Management:
missing
link
for
SOA
๏ hhp://sanjiva.weerawarana.org/2012/08/api-­‐management-­‐missing-­‐link-­‐for-­‐
soa.html
๏ Promo)ng
Service
Reuse
๏ hhp://wso2.com/whitepapers/promo)ng-­‐service-­‐reuse-­‐within-­‐your-­‐enterprise-­‐
and-­‐maximizing-­‐soa-­‐success/
37
Thursday, March 27, 14

38. Download
API
Manager
today!
๏ hhp://wso2.com/products/api-­‐manager/
38
Thursday, March 27, 14

39. Contact
us
!
Thursday, March 27, 14