API Workshop

Ronnie Mitra

Principal API Architect - Europe

Layer 7 API Academy

API Management

virtual cloud on-premise

API Academy

Mike Amundsen Ronnie Mitra

www.apiacademy.co

Business of APIs

API Styles

Usability

Security

API Architecture

SOA Governance

What are Web APIs?

Connecting things

Connecting computer programs

API

All programmers are API designers

Connections between modules

Language Dependant

APIs are constrained by the syntax of the language

… over the web

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

Web of

Documents

Web of

Apps Web of

Services

Web of

Things

The web is ubiquitous

And universally accessible

Publishers retain control

We are surrounded by Web APIs

Did you check the weather today?

Private or Closed APIs

Acme Corp. API

Acme Corp. App

Public or Open APIs

Acme Corp. API

Third Party App

Priority: Lower Cost

Priority: Increased Adoption

Business of APIs

why build an API?

Innovation

Consumer Reach

Revenue Source

Marketing

Integration

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

Innovation

Consumer Reach

Revenue Source

Marketing

Integration

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

Revenue Source

Revenue Source

http://www.flickr.com/photos/inside-south-africa/485356704

£0.10 per API Call

Revenue Source

1000 calls/month

5000 calls/month

Revenue Source

500 calls/month

1000 calls/month

5000 calls/month

Revenue Source

Is your content worth paying for?

Innovation

Consumer Reach

Revenue Source

Marketing

Integration

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

Consumer Reach

Consumer Reach

Head

Long Tail

Consumer Reach

Innovation

Consumer Reach

Revenue Source

Marketing

Integration

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

Marketing

Affiliate Programs

Sometimes you pay the developer.

Marketing

Draw new visitors in.

Marketing

Innovation

Consumer Reach

Revenue Source

Marketing

Integration

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

Innovation

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

Innovation from within

Innovation

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

Innovation outside your borders

Innovation

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

When does innovation happen?

Innovation

Consumer Reach

Revenue Source

Marketing

Integration

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

Integration

Business driven integration

Regulatory driven integration

Observational Learning: Five Short Stories of Public APIs

2000 – ebay

Started with a paid developer program in 2000

Made it free in 2005

Consumer Reach

Marketing

Large developer eco-system Large app eco-system

25% of eBay listings come from their API!

salesforce

2000 – salesforce

Integration

Revenue Source

API as a cloud enabler

2004 – Flickr

web 2.0 generation

Consumer Reach

Marketing

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

2006 – Amazon Web Services

Started as an online book shop… Became a department store…

now?

Jeff Bezos Connect everything

http://www.flickr.com/photos/zippy/2430495092

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

Revenue Source

Estimated revenue: $1.5B in 2012

http://wikibon.org/wiki/v/Cloud_Computing_2013%3A_The_Amazon_Gorilla_Invades_the_Enterprise

Twilio or stripe

2007 - Twillio

Revenue Source

The API is the business

100,000 developer milestone in 2012

Original APIs are still successful

New business models have emerged

Different drivers have influenced API design

Summary

Why make an API Public?

Unlock new markets

External innovation

Drive revenue

“Free” development

Crowdbased asset development

Promote Mutual Gain

(Symbiosis)

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

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

Don’t forget:

More developers = Higher Costs

Bandwidth

Technical Support

Processing and Storage

?

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

API Management

To ensure failure, make your API:

• difficult to understand

• dangerous to use (unsafe)

• unreliable and unstable

• opaque (provides no visibility)

API management helps us:

• Drive adoption

• Lower costs

• Keep existing users

• Reduce friction

Innovation

Consumer Reach

Revenue Source

Marketing

Integration

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

Without API management an API is naked.

Business of APIs Summary

• Understand the business motivation

• Choose a style that fits your constraints and goals

API Styles

What does a Web API look like?

Web APIs

HTTP

Architectural Styles

Tunnel Style

URI Style

Hypermedia Style

Event Driven Style

Tunnel Style Example: SOAP

• transport agnostic • operation based • binding documents (WSDL)

Tunnel Style

<RetrieveStudentRecords> <StudentId>1213</StudentId> </RetrieveStudentRecords>

Tunnel Style

• lots of tooling • not restricted to HTTP • RPC

Advantages

Tunnel Style

• inefficient for HTTP • increased learning curve • lack of tooling in mobile

Trade-offs

URI Style

GET PUT

POST DELETE

+ URI

URI Style

GET /students/1232

URI Style

• familiar to web developers • designed for HTTP • URIs are intuitive

Advantages

URI Style

• limited to four methods • URI design is not standard • can be ‘chatty’

Trade-offs

Hypermedia Style

Hypermedia Style

• links • templated input (forms) • task based

{ links: [ link {href: ‘…’ rel: ‘list’}, link {href: ‘…’ rel: ‘add’} ] collection: [ {link: {rel:'complete',href:‘…'},

id:42,

text:‘Record 42'

} ] }

Hypermedia Style

• designed for HTTP • long lasting • no URI construction

Advantages

Hypermedia Style

• leading-edge • requires ‘smarter’ apps • less familiar to developers

Trade-offs

Event Driven Style Example: WebSockets

• event based communication • server initiated events • full-duplex (websocket)

Event Driven Style

• less overhead • better performance

Advantages

Event Driven Style

• not HTTP-based • resource intensive connections • inefficient for request-reply

Trade-offs

API Styles Summary

• Web API != standard

• Four popular styles: Tunnel, URI, Hypermedia, Event

• Choose a style that fits your constraints and goals

Usability

Interaction Design

Usability

Human-Computer-Interaction

User Experience Design

Goal Oriented Design

A user-centric view of design.

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

Well designed products are easier to use.

Good design matters for Web APIs too.

“Frictionless” integration High rates of adoption Low cost integration

We want:

Focus on the developer experience

(dx)

Portal

API

Why is this difficult?

Reason #1

We project our own perspective.

Your code is not your API.

Your data model is not your API.

Reason #2

We project our own biases.

Never use SOAP?

Why?

Consider keyboards…

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

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

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

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

What matters is what your developer base thinks!

Reason #3

We make bad assumptions.

API publishers are also developers.

Reason #4

We lack the time, money or incentive for good design

“Best practices”, patterns and standards become shortcuts

Am I RESTfull enough?

So, how can we do better?

Developer-centric design requires effort and diligence.

Is the answer an SDK?

An SDK shifts the design effort but does not resolve the usability

challenge

Design with the developer in mind.

Ask them.

• Interviews

• Surveys

• Listen (blogs, presentations, tweets)

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

• Observe

• Prototype

• Historical Data

Consider all aspects of the DX:

Registration

Security

Troubleshooting

Learning

Interface Style

Registration

Lazy Registration

Social Integration

Personalization

Development Activity Cycle

1. Learn

2. Code

3. Implement

4. Test

5. Fix

Portal

API

Learn

Code

Test

API

Learn

Test

API explorers and “live documentation” can shorten the

gap between visibility and feedback.

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?

Focus on the interactions that take place, rather than the interfaces

we expose

Great API design can thrive in a developer-centric environment

Usability Summary

• Focus on the developer

• Start by thinking in terms of interactions

• Effective for public and private APIs

Securing APIs

OWASP Top Ten (2010 Edition)

Source: http://www.owasp.org/index.php/Top_10

The primary API management challenge:

Balancing Control and Accessibility

Identity Authentication Authorization Availability Integrity Privacy

TLS OAuth 2

Open ID Connect

OAuth provides a

Delegated Authorization Framework

An imperfect analogy….

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

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

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

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

I won’t tell.

I promise!

www.flickr.com/photos/auntiep/255249516

Granting access to someone to act

on your behalf.

Your resources

This app needs to act on your behalf

You need to grant access to your resources

Your google+ data

This app needs to access your Google+ data

You need to grant access to your resources

Hi Google.

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

Hang on, let me ask…

He said yes. Here is your

access code.

Proprietary authorization implementations

OAuth (2007)

OWrap

OAuth 2

History of OAuth

OAuth 2 Grant Types

Grant Types:

- Authorization Code

- Implicit

- Resource Owner Password Credentials

- Client Credentials

OAuth 2 Challenges

It is a framework

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

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

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

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

Security Summary

• Keep focus on usability

• Utilize standards like OAuth and TLS

• Danger in poor implementations

Designing an API Architecture

http://www.flickr.com/photos/naomi_pincher/3306312873/

Layered Pattern

Representation Layer

Component != Connector

Component

Database

File System

Message Queue

Transaction Manager

Source Code

Components Are Private

Connector

Web Server

Browser Agent

Proxy Server

Shared Cache

Connectors Are Public

Client Server Connectors

Components

The Web

The Treachery of Images - René Magritte

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

• Data and Interface Transformation • Focus on the interface (usability)

Representation

SOAP

Legacy

Security Layer

Security implementations are difficult:

• Mistakes are costly • Hard to understand specifications • Performance can suffer

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

Caching Layer

Caching Layer

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.

Orchestration Layer

• Chaining multiple calls • Aggregating and enriching data • ‘mashup’ external data with internal data

Orchestration:

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

API Gateway

Gateway

API

API

Restrict Access Improve Performance Focus on Usability

The gateway doesn’t solve all our problems

API portals

Portal

API Management

Portal

Gateway

API

API

We also apply this philosophy behind the firewall.

Architecture Summary

• Use a layered architecture

• Deploy a gateway for runtime

• Deploy a portal for developers

SOA Governance vs. API Management

Web APIs: New and Exciting!

http://www.flickr.com/photos/every1knows/4191971139

“Web APIs? I’ve been doing that for years.”

Image courtesy of http://www.flickr.com/photos/en321/3902138429/

Web APIs offer us a new perspective

http://www.flickr.com/photos/mugley/4407790613

The Modern Philosophy of the Web API:

• self service

• lower barriers and lower costs

• developer-centric

All hail the developer kings!

SOA Governance

Enforce access control Promote service usage Provide service discovery documents Provide service usage visibility

API Management

Enforce access control Promote API usage Provide API documentation Provide API usage visibility

SOA Governance

How do we make sure that these services are used properly?

API Management

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

Controlled versus Organic

Representing organizations is useful Complexity sucks Focus on the user

What can we learn from SOA Governance?

Web APIs are acting on a planetary scale

Service

Service

Service

ESB

ISB

API

API

API

SOA Governance Summary

• Different but converging

• Developer based perspective

• Based on success

API Workshop

Ronnie Mitra

Principal API Architect - Europe

Layer 7 API Academy