John Musser

CEO, ProgrammableWeb

@johnmusser

What Makes a

Great Open API?

Safe Harbor

Safe harbor statement under the Private Securities Litigation Reform Act of 1995:

This presentation may contain forward-looking statements that involve risks, uncertainties, and assumptions. If any such uncertainties

materialize or if any of the assumptions proves incorrect, the results of salesforce.com, inc. could differ materially from the results

expressed or implied by the forward-looking statements we make. All statements other than statements of historical fact could be

deemed forward-looking, including any projections of product or service availability, subscriber growth, earnings, revenues, or other

financial items and any statements regarding strategies or plans of management for future operations, statements of belief, any

statements concerning new, planned, or upgraded services or technology developments and customer contracts or use of our services.

The risks and uncertainties referred to above include – but are not limited to – risks associated with developing and delivering new

functionality for our service, new products and services, our new business model, our past operating losses, possible fluctuations in our

operating results and rate of growth, interruptions or delays in our Web hosting, breach of our security measures, the outcome of

intellectual property and other litigation, risks associated with possible mergers and acquisitions, the immature market in which we

operate, our relatively limited operating history, our ability to expand, retain, and motivate our employees and manage our growth, new

releases of our service and successful customer deployment, our limited history reselling non-salesforce.com products, and utilization

and selling to larger enterprise customers. Further information on potential factors that could affect the financial results of

salesforce.com, inc. is included in our annual report on Form 10-Q for the most recent fiscal quarter ended July 31, 2012. This

documents and others containing important disclosures are available on the SEC Filings section of the Investor Information section of

our Web site.

Any unreleased services or features referenced in this or other presentations, press releases or public statements are not currently

available and may not be delivered on time or at all. Customers who purchase our services should make the purchase decisions based

upon features that are currently available. Salesforce.com, inc. assumes no obligation and does not intend to update these forward-

looking statements.

Why does having

a great API

matter?

API growth rate Based on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012

API growth rate Based on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012

8 Years

18 Months

9 Months

6 Months

4 Months

3 Months

API Billionaires Club

5 billion API calls / day (April 2010)

1 billion API calls / day (Q1 2012)

5 billion API calls / day (October 2009)

13 billion API calls / day (May 2011)

1.4 billion API calls / day (May 2012)

1 billion API calls / day (January 2012)

1.1 billion API calls / day (April 2011)

1 billion API calls / day (May 2012)

Apps & devices everywhere

5 Keys to a Great API

Valuable

Planned

Flexible

Managed

Supported

5 Keys to a Great API

A valuable service (data, function, audience, …)

A plan and a business model

Simple, flexible, easily adopted

Managed and measured

Great developer support

Each “key” has

two sides:

business technology &

(each supports the other)

Each “key” has

two sides:

business technology &

(today’s talk)

These are really, really

hard to do right

5 Keys to a Great API

Valuable

Planned

Flexible

Managed

Supported

Valuable Service

Valuable Data

Valuable Audience

Valuable Function

Valuable Marketplace

Valuable Access

A very valuable API

service hides many sins

the API Value Corollary A great API on a bad service

is lipstick on a pig

5 Keys to a Great API

Valuable

Planned

Flexible

Managed

Supported

5 Keys to a Great API

Valuable

Planned (designed)

Flexible

Managed

Supported

Your first two design questions

What is the goal of this API?

(purpose)

Who will be using this API?

(audience)

You’ll face many design questions What protocol(s) will I support?

What data format(s) to provide? How will I manage security?

Which design patterns to use? Hmm, are there any?

Oh, right, I need to do versioning too…

Should I use an open source framework?

What is the price of IBM? GET http://example.org/stock/IBM POST /GetStock HTTP/1.1

Host: www.example.org

Content-Type: application/soap+xml

<?xml version="1.0"?>

<soap:Envelope

xmlns:soap="http://www.w3.org/2001/12/soap-

envelope"

soap:encodingStyle="http://www.w3.org/2001/12/so

ap-encoding">

<soap:Body

xmlns:m="http://www.example.org/stock">

<m:GetStockPrice>

<m:StockName>IBM</m:StockName>

</m:GetStockPrice>

</soap:Body>

</soap:Envelope>

GET http://example.org/stock/IBM POST /GetStock HTTP/1.1

Host: www.example.org

Content-Type: application/soap+xml

<?xml version="1.0"?>

<soap:Envelope

xmlns:soap="http://www.w3.org/2001/12/soap-

envelope"

soap:encodingStyle="http://www.w3.org/2001/12/so

ap-encoding">

<soap:Body

xmlns:m="http://www.example.org/stock">

<m:GetStockPrice>

<m:StockName>IBM</m:StockName>

</m:GetStockPrice>

</soap:Body>

</soap:Envelope>

SOAP REST

API protocols and styles Based on directory of 6,200 web APIs listed at ProgrammableWeb, June 2012

A great API doesn’t

just ask

“am I RESTful enough? ”

Daniel Jacobson, Netflix Engineering Blog, July 9, 2012

Daniel Jacobson, Netflix Engineering Blog, July 9, 2012

A great API

understands

its audience

another moral of that story

is…

Your audience may <3 SOAP, really

50+ finance APIs, 5 billion+ calls/month

Best data format? It depends…

XML, JSON, RSS, Atom, YAML, iCalendar, CSV,

Serialized PHP, HTML, PNG, GeoRSS, vCard,

Text, RDF, OPML, MediaRSS, VML, TV-Anytime,

hCalendar, FOAF, XSPF, SQL, GML, CDF

Data formats supported by APIs on ProgrammableWeb, May 2012

What is the price of IBM? <?xml version="1.0"?>

<soap:Envelope

xmlns:soap="http://www.w3.org/2001/12/soap-envelope"

soap:encodingStyle="http://www.w3.org/2001/12/soap-

encoding">

<soap:Body xmlns:m="http://www.example.org/stock">

<m:GetStockPriceResponse>

<m:Price>34.5</m:Price>

</m:GetStockPriceResponse>

</soap:Body>

</soap:Envelope>

{

"symbol": ”IBM",

"price": 94.72,

}

JSON XML <?xml version="1.0"?>

<soap:Envelope

xmlns:soap="http://www.w3.org/2001/12/soap-envelope"

soap:encodingStyle="http://www.w3.org/2001/12/soap-

encoding">

<soap:Body xmlns:m="http://www.example.org/stock">

<m:GetStockPriceResponse>

<m:Price>34.5</m:Price>

</m:GetStockPriceResponse>

</soap:Body>

</soap:Envelope>

{

"symbol": ”IBM",

"price": 94.72,

}

Percentage of REST APIs supporting JSON Based on directory of 6,200 web APIs listed at ProgrammableWeb, June 2012

Want to discuss API design?

Check out API Craft http://groups.google.com/group/api-craft

5 Keys to a Great API

Valuable

Planned

(simple) Flexible (easily adopted)

Managed

Supported

API simplicity continuum

Simple Complex

“As simple as possible, but no simpler”

What makes an API flexible? Provides choices

data format, protocol, version

Gives developer control partial queries & updates, batch operations

Offers advanced options webhooks, streaming, caching

What’s your TTFHW?

Time To First “Hello World”

aka: how long from zero to 60?

6 ways to accelerate TTFHW

#1) Make it clear what you do

#2) Offer free or trial access

(or, even both free & trial)

#3) Fast, automated signup

(so fast, you can even skip this

step till you’re convinced…)

#4) Clear, accurate documentation

#5) Copious code samples

#6) Provide tools

Twilio’s debugger

Stripe’s dashboard

Wordnik’s Swagger & Mashery’s I/O Docs

Google’s

OAuth

Playground

Apigee’s API console

5 Keys to a Great API

Valuable

Planned

Flexibile

Managed (easily adopted)

Supported

What to manage & measure?

Manage

Security

Key management

Monitoring

Reporting

Scaling

Rate limiting

Versioning

Measure

Performance

Developers and apps

Quality

Marketing

Revenue

Volume

Trends

API versioning in REST

Where What Who Example

Path segment Date Twilio /2010-04-01/…

Path segment Number Twitter /1/…

Path segment ‘v’ + Number LinkedIn /v1/…

Query string Number Google ?v=2

Custom HTTP header Number Google GData-Version: 2

HTTP Accept header Number Github application/vnd.github[.version]

It matters less how

you version than you do

version

API security baseline Today:

SSL as option

OAuth 2.0 (one of the few API standards with traction)

Future:

SSL required (many major APIs moving to SSL only)

OpenID Connect (it’s very early today)

Great APIs get meausred

Metrics that matter Traffi

c Total calls

Top methods

Call chains

Quota faults

Developers Total developers

Active developers

Top developers

Trending apps

Service Performance

Availability

Error rates

Code defects

Marketing Dev registrations

Dev portal funnel

Traffic sources

Event metrics

Support Support tickets

Response times

Community metrics

Business Direct revenue

Indirect revenue

Market share

Costs

Great APIs prioritize

what they want to

measure

“The absence of

limitations is the

enemy of art” Orson Welles

5 Keys to a Great API

Valuable

Planned

Flexible

Managed

Supported

What makes an API supported? Great developer experience (DX) signup, guides, reference, SDKs, pricing, clear ToS

Communication & community forum, blog, social media, email, app gallery

Great support / evangelism teams active, engaged, listening, responding, at events

What makes an API supported? Great developer experience (DX) signup, guides, reference, SDKs, pricing, clear ToS

Communication & community forum, blog, social media, email, app gallery

Great support / evangelism teams active, engaged, listening, responding, at events

developerexperience.org

see also

developer-support-handbook.appspot.com

Great DX separates the

best APIs from

the rest

Covering your DX checklist

Does API design impact support?

Let me count the ways…

For example, look at Twilio’s error

response

Community:

never underestimate the value

5 Keys to a Great API

Valuable

Planned

Flexible

Managed

Supported

Top 10 API worst practices 10. Poor error handing

9. REST APIs that ignore HTTP rules

8. Exposing your raw underlying data model

7. Security complexity

6. Unexpected & undocumented releases

5. Poor developer experience

4. Expect an MVC framework ‘gives’ you a great API

3. Assume if you build it they will come

2. Inadequate support

1. Poor documentation

A great API

is a journey,

not a destination

Thank You

Questions, ideas,

comments?john@programmablewe

b.com

@johnmusser

Photo Credits

Pig: http://www.flickr.com/photos/babasteve/7341687640/

Race car: http://www.flickr.com/photos/lim_lik_wei/3270522646/

Stopwatch: http://www.flickr.com/photos/purplemattfish/3020016417/

Hackers: http://www.flickr.com/photos/hackny/5684846071/

Winding road: http://www.flickr.com/photos/matthewthecoolguy/7518274258/