What Makes a Great Open API?
232 likes91,493 views
The document outlines the essential components that contribute to a great API, highlighting five key elements: value, planning, flexibility, management, and support. It emphasizes the importance of understanding the audience, providing versatile options, and maintaining strong developer support along with effective measurement and security practices. The overall message underscores that building a successful API is an ongoing process that requires continuous improvement and adaptation.
![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]](https://image.slidesharecdn.com/jmusserosconapis2012-120719031827-phpapp01/85/What-Makes-a-Great-Open-API-53-320.jpg)
What Makes a Great Open API?
- 1. What Makes a Great Open API? John Musser, ProgrammableWeb @johnmusser OSCON 2012
- 2. yea rs 7 Is ,000 AP tor ies 6 new s s 3 ,000
- 3. Why does having a great API matter?
- 4. API growth rate Based on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012
- 5. 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
- 6. 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)
- 7. Apps & devices everywhere
- 8. 5 Keys to a Great API Valuable Planned Flexible Managed Supported
- 9. 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
- 10. Each “key” has two sides: business & technology (each supports the other)
- 11. Each “key” has two sides: business & technology (today’s talk)
- 12. ET #1 I SECR A P These are really, really hard to do right
- 13. 5 Keys to a Great API Valuable Planned Flexible Managed Supported
- 14. Valuable Service
- 15. Valuable Data
- 19. Valuable Access
- 20. ET #2 I SECR A P A very valuable service hides many API sins
- 21. the API Value Corollary The API value corollary A great API on a bad service is lipstick on a pig
- 22. 5 Keys to a Great API Valuable Planned Flexible Managed Supported
- 23. 5 Keys to a Great API Valuable Planned (designed) Flexible Managed Supported
- 24. Your first two design questions What is the goal of this API? (purpose) Who will be using this API? (audience)
- 25. You’ll make many design choices 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…
- 26. What’s the price of IBM? POST /GetStock HTTP/1.1 GET h@p://example.org/stock/IBM 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>
- 27. SOAP REST POST /GetStock HTTP/1.1 GET h@p://example.org/stock/IBM 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>
- 28. API protocols and styles Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012
- 29. ET #3 I SECR A P A great API doesn’t just ask “am I RESTful enough? ”
- 30. Daniel Jacobson, Netflix Engineering Blog, July 9, 2012
- 31. Daniel Jacobson, Netflix Engineering Blog, July 9, 2012
- 32. another moral of that story is… A great API understands its audience
- 33. Your audience may <3 SOAP, really 50+ finance APIs, 5 billion+ calls/month
- 34. 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
- 35. What’s the price of IBM? { <?xml version="1.0"?> "symbol": ”IBM", <soap:Envelope "price": 94.72, 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>
- 36. JSON XML { <?xml version="1.0"?> "symbol": ”IBM", <soap:Envelope "price": 94.72, 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>
- 37. Percentage of REST APIs supporting JSON Based on directory of 5,800 web APIs listed at ProgrammableWeb, May 2012
- 38. Want to discuss API design? Check out API Craft http://groups.google.com/group/api-craft
- 39. 5 Keys to a Great API Valuable Planned (simple) Flexible (easily adopted) Managed Supported
- 40. API simplicity continuum Simple Complex “As simple as possible, but no simpler”
- 41. 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
- 42. What’s your TTFHW? Time To First “Hello World” aka: how long from zero to 60?
- 43. 6 ways to accelerate TTFHW
- 44. #1) Make it clear what you do
- 45. #2) Offer “Free” or “Trial” API access
- 46. (or, even both free & trial)
- 47. #3) Fast, automated signup (so fast, you can even skip this step till you’re convinced…)
- 48. #4) Clear, accurate documentation
- 49. #5) Copious code samples
- 50. Stripe’s dashboard #6) Provide tools Google’s OAuth Playground Wordnik’s Swagger & Mashery’s I/O Docs Apigee’s API console Twilio’s debugger
- 51. 5 Keys to a Great API Valuable Planned Flexible Managed (and measured) Supported
- 52. What to manage & measure? Manage Measure Security Performance Key management Developers and apps Monitoring Quality Reporting Marketing Scaling Revenue Rate limiting Volume Versioning Trends
- 53. 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]
- 54. ET #4 I SECR A P It matters less how you version than you do version
- 55. 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)
- 56. Great APIs get measured Great APIs get measured
- 57. Metrics that matter Traffic Developers Service Total developers Performance Total calls Active developers Availability Top methods Top developers Error rates Call chains Trending apps Code defects Quota faults Retention Marketing Support Business Dev registrations Direct revenue Support tickets Indirect revenue Dev portal funnel Response times Market share Traffic sources Community metrics Costs Event metrics
- 58. ET #5 I SECR A P Great APIs prioritize what they want to measure
- 59. “The absence of limitations is the enemy of art” Orson Welles
- 60. 5 Keys to a Great API Valuable Planned Flexible Managed Supported
- 61. 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
- 62. What makes an API supported? Great developer experience (DX) A nd reference, SDKs, pricing, legal g Signup, guides, ythin er & communityr ev Communication d un de c ereemail, events, clear ToS forum, blog,ov media, social /W teams Great supportHevangelism TF T listening, responding active, engaged,
- 63. developerexperience.org see also developer-support-handbook.appspot.com
- 64. ET #6 I SECR A P Great DX separates the best APIs from the rest
- 65. Covering your DX checklist
- 66. Does API design impact support? Let me count the ways… For example, look at Twilio’s error response
- 67. Community: a core tenet of great open APIs and open source
- 68. 5 Keys to a Great API Valuable e e m or A nd on Planned ing … Flexible th Managed Supported
- 69. 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
- 70. #7 P I SECR ET A great API A is a journey, not a destination
- 71. Thank You QuesRons, ideas, comments? [email protected] @johnmusser
- 72. 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/