What Makes a Great Open API?

What Makes a Great Open API?

John  Musser,  ProgrammableWeb  @johnmusser  OSCON  2012  

7  years  

6,000  APIs  

3,000  news  sto

ries  

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

API SECRET #1

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 service hides many API sins

API SECRET #2

The API value corollary

A great API on a bad service is lipstick on a pig

the API Value Corollary

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 make many design choices 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?

GET  h@p://example.org/stock/IBM  POST  /GetStock  HTTP/1.1  Host:  www.example.org  Content-­‐Type:  applicaRon/soap+xml    <?xml  version="1.0"?>  <soap:Envelope  xmlns:soap="h@p://www.w3.org/2001/12/soap-­‐envelope"  soap:encodingStyle="h@p://www.w3.org/2001/12/soap-­‐encoding">    <soap:Body  xmlns:m="h@p://www.example.org/stock">      <m:GetStockPrice>          <m:StockName>IBM</m:StockName>      </m:GetStockPrice>  </soap:Body>  </soap:Envelope>  

What’s the price of IBM?

GET  h@p://example.org/stock/IBM  POST  /GetStock  HTTP/1.1  Host:  www.example.org  Content-­‐Type:  applicaRon/soap+xml    <?xml  version="1.0"?>  <soap:Envelope  xmlns:soap="h@p://www.w3.org/2001/12/soap-­‐envelope"  soap:encodingStyle="h@p://www.w3.org/2001/12/soap-­‐encoding">    <soap:Body  xmlns:m="h@p://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 5,100 web APIs listed at ProgrammableWeb, February 2012

A great API doesn’t just ask

“am I RESTful enough? ”

API SECRET #3

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

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

{          "symbol":  ”IBM",          "price":  94.72,  }  

<?xml  version="1.0"?>  <soap:Envelope  xmlns:soap="h@p://www.w3.org/2001/12/soap-­‐envelope"  soap:encodingStyle="h@p://www.w3.org/2001/12/soap-­‐encoding">    <soap:Body  xmlns:m="h@p://www.example.org/stock">      <m:GetStockPriceResponse>          <m:Price>34.5</m:Price>      </m:GetStockPriceResponse>  </soap:Body>    </soap:Envelope>  

What’s the price of IBM?

{          "symbol":  ”IBM",          "price":  94.72,  }  

<?xml  version="1.0"?>  <soap:Envelope  xmlns:soap="h@p://www.w3.org/2001/12/soap-­‐envelope"  soap:encodingStyle="h@p://www.w3.org/2001/12/soap-­‐encoding">    <soap:Body  xmlns:m="h@p://www.example.org/stock">      <m:GetStockPriceResponse>          <m:Price>34.5</m:Price>      </m:GetStockPriceResponse>  </soap:Body>    </soap:Envelope>  

JSON XML

Percentage of REST APIs supporting JSON Based on directory of 5,800 web APIs listed at ProgrammableWeb, May 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” API 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 Flexible

Managed (and measured) 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   Twi@er   /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   applicaRon/vnd.github[.version]  

It matters less how you version than you do

version

API SECRET #4

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 measured Great APIs get measured

Metrics that matter Traffic

Total calls Top methods

Call chains Quota faults

Developers Total developers

Active developers Top developers Trending apps

Retention

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

API SECRET #5

“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

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

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

What makes an API supported? Great developer experience (DX)

Signup, guides, reference, SDKs, pricing, legal

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

Communication & community forum, blog, social media, email, events, clear ToS

And  everyt

hing  

covered  unde

r  

TTFHW  

developerexperience.org

see also developer-support-handbook.appspot.com

Great DX separates the best APIs from

the rest

API SECRET #6

Covering your DX checklist

Does API design impact support? Let me count the ways…

For example, look at Twilio’s error response

Community: a core tenet of great open APIs and open source

5 Keys to a Great API Valuable Planned Flexible

Managed Supported

And  one  more  

thing…  

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

API SECRET #7

Thank You

QuesRons,  ideas,  comments?john@programmableweb.com  

@johnmusser    

Photo  credits  Pig:  h@p://www.flickr.com/photos/babasteve/7341687640/  Race  car:  h@p://www.flickr.com/photos/lim_lik_wei/3270522646/  Stopwatch:  h@p://www.flickr.com/photos/purplemapish/3020016417/  Hackers:  h@p://www.flickr.com/photos/hackny/5684846071/  Winding  road:  h@p://www.flickr.com/photos/ma@hewthecoolguy/7518274258/