Download - What Makes a Great Open API?
![Page 1: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/1.jpg)
John Musser
CEO, ProgrammableWeb
@johnmusser
What Makes a
Great Open API?
![Page 2: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/2.jpg)
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.
![Page 3: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/3.jpg)
![Page 4: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/4.jpg)
Why does having
a great API
matter?
![Page 5: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/5.jpg)
API growth rate Based on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012
![Page 6: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/6.jpg)
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
![Page 7: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/7.jpg)
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)
![Page 8: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/8.jpg)
Apps & devices everywhere
![Page 9: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/9.jpg)
5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported
![Page 10: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/10.jpg)
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
![Page 11: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/11.jpg)
Each “key” has
two sides:
business technology &
(each supports the other)
![Page 12: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/12.jpg)
Each “key” has
two sides:
business technology &
(today’s talk)
![Page 13: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/13.jpg)
These are really, really
hard to do right
![Page 14: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/14.jpg)
5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported
![Page 15: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/15.jpg)
Valuable Service
![Page 16: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/16.jpg)
Valuable Data
![Page 17: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/17.jpg)
Valuable Audience
![Page 18: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/18.jpg)
Valuable Function
![Page 19: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/19.jpg)
Valuable Marketplace
![Page 20: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/20.jpg)
Valuable Access
![Page 21: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/21.jpg)
A very valuable API
service hides many sins
![Page 22: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/22.jpg)
the API Value Corollary A great API on a bad service
is lipstick on a pig
![Page 23: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/23.jpg)
5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported
![Page 24: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/24.jpg)
5 Keys to a Great API
Valuable
Planned (designed)
Flexible
Managed
Supported
![Page 25: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/25.jpg)
Your first two design questions
What is the goal of this API?
(purpose)
Who will be using this API?
(audience)
![Page 26: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/26.jpg)
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?
![Page 27: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/27.jpg)
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>
![Page 28: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/28.jpg)
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
![Page 29: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/29.jpg)
API protocols and styles Based on directory of 6,200 web APIs listed at ProgrammableWeb, June 2012
![Page 30: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/30.jpg)
A great API doesn’t
just ask
“am I RESTful enough? ”
![Page 31: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/31.jpg)
Daniel Jacobson, Netflix Engineering Blog, July 9, 2012
![Page 32: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/32.jpg)
Daniel Jacobson, Netflix Engineering Blog, July 9, 2012
![Page 33: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/33.jpg)
A great API
understands
its audience
another moral of that story
is…
![Page 34: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/34.jpg)
Your audience may <3 SOAP, really
50+ finance APIs, 5 billion+ calls/month
![Page 35: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/35.jpg)
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
![Page 36: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/36.jpg)
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,
}
![Page 37: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/37.jpg)
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,
}
![Page 38: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/38.jpg)
Percentage of REST APIs supporting JSON Based on directory of 6,200 web APIs listed at ProgrammableWeb, June 2012
![Page 39: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/39.jpg)
Want to discuss API design?
Check out API Craft http://groups.google.com/group/api-craft
![Page 40: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/40.jpg)
5 Keys to a Great API
Valuable
Planned
(simple) Flexible (easily adopted)
Managed
Supported
![Page 41: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/41.jpg)
API simplicity continuum
Simple Complex
“As simple as possible, but no simpler”
![Page 42: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/42.jpg)
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
![Page 43: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/43.jpg)
What’s your TTFHW?
Time To First “Hello World”
aka: how long from zero to 60?
![Page 44: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/44.jpg)
6 ways to accelerate TTFHW
![Page 45: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/45.jpg)
#1) Make it clear what you do
![Page 46: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/46.jpg)
#2) Offer free or trial access
![Page 47: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/47.jpg)
(or, even both free & trial)
![Page 48: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/48.jpg)
#3) Fast, automated signup
(so fast, you can even skip this
step till you’re convinced…)
![Page 49: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/49.jpg)
#4) Clear, accurate documentation
![Page 50: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/50.jpg)
#5) Copious code samples
![Page 51: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/51.jpg)
#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
![Page 52: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/52.jpg)
5 Keys to a Great API
Valuable
Planned
Flexibile
Managed (easily adopted)
Supported
![Page 53: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/53.jpg)
What to manage & measure?
Manage
Security
Key management
Monitoring
Reporting
Scaling
Rate limiting
Versioning
Measure
Performance
Developers and apps
Quality
Marketing
Revenue
Volume
Trends
![Page 54: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/54.jpg)
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]
![Page 55: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/55.jpg)
It matters less how
you version than you do
version
![Page 56: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/56.jpg)
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)
![Page 57: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/57.jpg)
Great APIs get meausred
![Page 58: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/58.jpg)
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
![Page 59: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/59.jpg)
Great APIs prioritize
what they want to
measure
![Page 60: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/60.jpg)
“The absence of
limitations is the
enemy of art” Orson Welles
![Page 61: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/61.jpg)
5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported
![Page 62: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/62.jpg)
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
![Page 63: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/63.jpg)
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
![Page 64: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/64.jpg)
developerexperience.org
see also
developer-support-handbook.appspot.com
![Page 65: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/65.jpg)
Great DX separates the
best APIs from
the rest
![Page 66: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/66.jpg)
Covering your DX checklist
![Page 67: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/67.jpg)
Does API design impact support?
Let me count the ways…
For example, look at Twilio’s error
response
![Page 68: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/68.jpg)
Community:
never underestimate the value
![Page 69: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/69.jpg)
5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported
![Page 70: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/70.jpg)
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
![Page 71: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/71.jpg)
A great API
is a journey,
not a destination
![Page 72: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/72.jpg)
Thank You
Questions, ideas,
comments?john@programmablewe
b.com
@johnmusser
![Page 73: What Makes a Great Open API?](https://reader031.vdocument.in/reader031/viewer/2022020717/55528477b4c905b4598b512b/html5/thumbnails/73.jpg)
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/