1. What Makes a
Great Open API?
John Musser
CEO, ProgrammableWeb
@johnmusser

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

4. Why does having
a great API
matter?

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

6. 3 Months
4 Months
6 Months
9 Months
18 Months
8 Years
API growth rate
Based on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012

7. API Billionaires Club
13 billion API calls / day (May 2011)
5 billion API calls / day (April 2010)
5 billion API calls / day (October 2009)
1.4 billion API calls / day (May 2012)
1.1 billion API calls / day (April 2011)
1 billion API calls / day (May 2012)
1 billion API calls / day (Q1 2012)
1 billion API calls / day (January 2012)

8. Apps & devices everywhere

9. 5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported

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

11. Each “key” has
two sides:
business & technology
(each supports the other)

12. Each “key” has
two sides:
business & technology
(today’s talk)

13. These are really, really
hard to do right

14. 5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported

15. Valuable Service

16. Valuable Data

17. Valuable Audience

18. Valuable Function

19. Valuable Marketplace

20. Valuable Access

21. A very valuable API
service hides many sins

22. A great API on a bad service
the API Value Corollary
is lipstick on a pig

23. 5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported

24. 5 Keys to a Great API
Valuable
Planned (designed)
Flexible
Managed
Supported

25. Your first two design questions
What is the goal of this API?
(purpose)
Who will be using this API?
(audience)

26. You’ll face many design questions
What protocol(s) will I support?
What data format(s) to provide?
How will I manage security?
Should I use an open source framework?
Which design patterns to use? Hmm, are there any?
Oh, right, I need to do versioning too…

27. What is the price of IBM?
POST /GetStock HTTP/1.1 GET http://example.org/stock/IBM
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>

28. SOAP REST
POST /GetStock HTTP/1.1 GET http://example.org/stock/IBM
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>

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

30. A great API doesn’t
just ask
“am I RESTful enough? ”

31. Daniel Jacobson, Netflix Engineering Blog, July 9, 2012

32. Daniel Jacobson, Netflix Engineering Blog, July 9, 2012

33. another moral of that story
is…
A great API
understands
its audience

34. Your audience may <3 SOAP, really
50+ finance APIs, 5 billion+ calls/month

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

36. What is the price of IBM?
{ <?xml version="1.0"?>
"symbol": ”IBM", <soap:Envelope
"price": 94.72, 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>

37. JSON XML
{ <?xml version="1.0"?>
"symbol": ”IBM", <soap:Envelope
"price": 94.72, 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>

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

39. Want to discuss API design?
Check out API Craft
http://groups.google.com/group/api-craft

40. 5 Keys to a Great API
Valuable
Planned
(simple) Flexible (easily adopted)
Managed
Supported

41. API simplicity continuum
Simple Complex
“As simple as possible, but no simpler”

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

43. What’s your TTFHW?
Time To First “Hello World”
aka: how long from zero to 60?

44. 6 ways to accelerate TTFHW

45. #1) Make it clear what you do

46. #2) Offer free or trial access

47. (or, even both free & trial)

48. #3) Fast, automated signup
(so fast, you can even skip this
step till you’re convinced…)

49. #4) Clear, accurate documentation

50. #5) Copious code samples

51. Stripe’s dashboard
#6) Provide tools
Google’s
OAuth
Wordnik’s Swagger & Mashery’s I/O Docs Playground
Apigee’s API console
Twilio’s debugger

52. 5 Keys to a Great API
Valuable
Planned
Flexibile
Managed (easily adopted)
Supported

53. What to manage & measure?
Manage Measure
Security Performance
Key management Developers and apps
Monitoring Quality
Reporting Marketing
Scaling Revenue
Rate limiting Volume
Versioning Trends

54. 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]

55. It matters less how
you version than you do
version

56. 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)

57. Great APIs get meausred

58. Metrics that matter
Traffi Developers Service
Total developers Performance
c Active developers Availability
Total calls Top developers Error rates
Top methods Trending apps Code defects
Call chains
Marketing
Quota faults
Support Business
Dev registrations Support tickets Direct revenue
Dev portal funnel Response times Indirect revenue
Traffic sources Community metrics Market share
Event metrics Costs

59. Great APIs prioritize
what they want to
measure

60. “The absence of
limitations is the
enemy of art”
Orson Welles

61. 5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported

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

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

64. developerexperience.org
see also
developer-support-handbook.appspot.com

65. Great DX separates the
best APIs from
the rest

66. Covering your DX checklist

67. Does API design impact support?
Let me count the ways…
For example, look at Twilio’s error
response

68. Community:
never underestimate the value

69. 5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported

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

71. A great API
is a journey,
not a destination

72. Thank You
Questions, ideas,
comments?john@programmablewe
b.com
@johnmusser

73. 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/