API Reliability Guide
3 likes3,447 views
The document is a comprehensive guide on API reliability and best practices, highlighting the importance of performance, simplicity, and user experience in mobile and web applications. It emphasizes choosing the right data formats like JSON, efficient versioning, and caching strategies for optimized API responses. Additionally, it includes multiple resources and examples for developers to enhance their API design and implementation skills.
![Static files
<?php
if ((is_file($_SERVER['SCRIPT_FILENAME'].'.json'))
&& (time()-filemtime($_SERVER['SCRIPT_FILENAME'].'.json') < 3600))
readfile($_SERVER['SCRIPT_FILENAME'].'.json');
exit;
}
// (the php script itself goes here)
echo $response;
$fp = fopen($_SERVER['SCRIPT_FILENAME'].'.json', 'w');
fwrite($fp, $response);
fclose($fp);
?>](https://image.slidesharecdn.com/psuweb12-api-120611102052-phpapp01/85/API-Reliability-Guide-54-320.jpg)
![JSONP
function handle_data(data) {
// `data` is now the object representation of the JSON data
}
---
http://some.tld/web/service?callback=handle_data:
---
handle_data({"data_1": "hello world", "data_2":
["the","sun","is","shining"]});](https://image.slidesharecdn.com/psuweb12-api-120611102052-phpapp01/85/API-Reliability-Guide-56-320.jpg)
API Reliability Guide
- 1. API Reliability Guide http://www.flickr.com/photos/erreeffe/3769670873/ @nickdenardis / #psuweb12
- 2. Nick DeNardis Associate Director of Web Communications at Wayne State University http://wayne.edu/ Host of EDU Checkup http://educheckup.com/ Curator of EDU Snippits http://edusnippits.com/ Writer for .eduGuru http://doteduguru.com/
- 5. Not just for robots http://www.flickr.com/photos/stevent/3241986538/
- 7. The API’s job is to make the developer as successful as possible http://knowyourmeme.com/memes/i-hate-sandcastles-success-kid
- 8. It makes the user experience can break http://www.flickr.com/photos/daychokesnight/2149714792/
- 12. Complications with mobile “always on”
- 13. Mobile isn’t going anywhere 1.45 Million devices per day 371,000 births per day http://www.lukew.com/ff/entry.asp?1506
- 14. Mobile Data Traffic Expected To Rise 40- Fold Over Next Five Years http://techcrunch.com/2010/03/30/mobile-data-traffic-rise-40-fold/
- 15. Mobile users use more bandwidth
- 16. Desktop 250 kb - Avg page weight 2.5 pages - Avg number per visit 1300 625 kb - Bandwidth per visit 975 650 Mobile 325 50 kb - Avg page weight 25 pages - Avg number per visit 0 Data Desktop Mobile 1.25 mb - Bandwidth per visit
- 17. Mobile Desktop 40 30 Millions of visitors 20 10 0 2009 2010 2011 2012 2013 2014 2015 2016 2017 http://wayne.edu/
- 18. The mobile Web is slow And it’s mostly our fault
- 19. You can’t blame the network for everything CSS Images Images New Content Javascript Initial HTML Cell Latency Cell Latency Time Time First Request Second Request
- 20. Do less better
- 21. One size != fit all https://api.twitter.com/1/ https://us2.api.mailchimp.com/1.3/ https://api.foursquare.com/v2/ https://api.instagram.com/v1/ https://www.salesforce.com/services/Soap/c/18.0 https://api.wayne.edu/v1/ Think versioning from the start
- 22. SOAP REST The request: The request: GET /StockPrice HTTP/1.1 GET /StockPrice/IBM HTTP/1.1 Host: example.org Host: example.org Content-Type: application/soap+xml; charset=utf-8 Accept: text/xml Content-Length: nnn Accept-Charset: utf-8 <?xml version="1.0"?> The response: <env:Envelope xmlns:env="http://www.w3.org/ 2003/05/soap-envelope" HTTP/1.1 200 OK xmlns:s="http://www.example.org/stock-service"> Content-Type: text/xml; charset=utf-8 <env:Body> Content-Length: nnn <s:GetStockQuote> <s:TickerSymbol>IBM</s:TickerSymbol> <?xml version="1.0"?> </s:GetStockQuote> <s:Quote xmlns:s="http://example.org/stock- </env:Body> service"> </env:Envelope> <s:TickerSymbol>IBM</s:TickerSymbol> <s:StockPrice>45.25</s:StockPrice> The response: </s:Quote> HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: nnn <?xml version="1.0"?> <env:Envelope xmlns:env="http://www.w3.org/ 2003/05/soap-envelope" xmlns:s="http://www.example.org/stock-service"> <env:Body> <s:GetStockQuoteResponse> <s:StockPrice>45.25</s:StockPrice> </s:GetStockQuoteResponse> </env:Body> </env:Envelope> 4 kb vs 2 kb Round Trip
- 23. Stick to REST
- 25. Your best friend JSON Easy to encode: $arr = array('a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5); json_encode($arr); Easy to decode: $json = '{"a":1,"b":2,"c":3,"d":4,"e":5}'; json_decode($json); Javascript: var myObject = eval('(' + json + ')'); Douglas Crockford
- 27. Flattened highed = More interfaces CRM CMS iModules Events Course Schedule Parking Flickr YouTube Faculty Profiles Library Catalog
- 28. Your data is everywhere Website CMS Gather & Clean Mobile Website Events Shadow storage Mobile App LDAP API Webserver Digital Signage Banner Third Party
- 29. API is the glue Website CMS Gather & Clean Mobile Website Events Shadow storage Mobile App LDAP API Webserver Digital Signage Banner Third Party
- 30. Rolling your own API Trust no one.
- 31. Making the glue Ingredients: Server space you control api.domain.edu or domain.edu/api Ability: • Database • Cronjobs • Server logs • Analytics • PHP accelerator • Xdebug
- 33. Documentation Design http://www.flickr.com/photos/edublogger/6950969837/
- 35. Affordance The physical design will communicate how it is suppose to be used http://www.flickr.com/photos/hawkexpress/269032594/
- 37. Create. Read. Update. Delete. http://www.flickr.com/photos/fss/2181882493/
- 39. GET /academic/colleges/listing GET /academic/colleges/info/150 REST Item Category Function Interface (Class)
- 40. GET /academic/colleges/listing GET /academic/colleges/info GET /academic/majors/listing GET /academic/majors/info GET /academic/classes/listing GET /academic/classes/info GET /parking/availability/listing GET /parking/availability/info
- 41. The devil is in the details Simple URL Response code Total count Data container Keep it lightweight 91 KB
- 42. Use only what you need Filters Less data 41 KB
- 43. Writing data
- 44. POST /admissions/rfi/add POST /admissions/visit/add POST /admissions/application/add POST /academic/colleges/add POST /academic/colleges/edit POST /academic/majors/add POST /academic/majors/edit Post data: id=3047
- 45. Soft Delete (keep all the data!)
- 46. POST /academic/colleges/remove POST /academic/majors/remove POST /academic/classes/remove POST /parking/availability/remove Post data: id=3047
- 47. Authentication /api/user/auth
- 48. Auth workflow Request API Key Rate Limit Username/Pass Session ID Check Credentials Session ID (Do work) Return
- 49. Rate Limiting 100 per minute per Key/IP
- 50. Cache. Cache. Cache.
- 52. APC <?php $bar = 'BAR'; apc_store('foo', $bar); var_dump(apc_fetch('foo')); ?>
- 54. Static files <?php if ((is_file($_SERVER['SCRIPT_FILENAME'].'.json')) && (time()-filemtime($_SERVER['SCRIPT_FILENAME'].'.json') < 3600)) readfile($_SERVER['SCRIPT_FILENAME'].'.json'); exit; } // (the php script itself goes here) echo $response; $fp = fopen($_SERVER['SCRIPT_FILENAME'].'.json', 'w'); fwrite($fp, $response); fclose($fp); ?>
- 55. HTML5 localStorage if (typeof(localStorage) == 'undefined' ) { alert('Your browser does not support HTML5 localStorage. Try upgrading.'); } else { try { localStorage.setItem("name", "Hello World!"); //saves to the database, } catch (e) { if (e == QUOTA_EXCEEDED_ERR) { alert('Quota exceeded!'); //data wasn't successfully saved due to quota exceed so throw an error } } document.write(localStorage.getItem("name")); //Hello World! localStorage.removeItem("name"); //deletes the matching item from the database } http://paperkilledrock.com/2010/05/html5-localstorage-part-one/
- 56. JSONP function handle_data(data) { // `data` is now the object representation of the JSON data } --- http://some.tld/web/service?callback=handle_data: --- handle_data({"data_1": "hello world", "data_2": ["the","sun","is","shining"]});
- 57. Expires header <?php header('Expires: '.gmdate('D, d M Y H:i:s GMT', time() + 3600)); ?> 1 Month 1 Week 1 Day Semesters Courses Events Subjects Media Experts News Degrees Map Categories No Cache Map Locations Course Availability Parking Availability
- 58. Our Stats Feb 2011 - In production 6.1 million requests 48% from mobile 21% iOS 23% Android 66% Web 95% GET’s 16 ms average response time
- 59. Examples
- 60. Mobile news
- 62. maps/locations/listing Google API events/event/listing directory/people/listing academic/courses/listing
- 63. maps/category/listing events/event/listing maps/location/info
- 64. faculty/profile/info go/url/info
- 65. Hackathon Community through data http://www.flickr.com/photos/hackny/5684887983/
- 66. Resources • http://apigee.com/ • http://rubyonrails.org/ • http://cakephp.org/ • https://groups.google.com/group/api-craft/ • http://37signals.com/svn/posts/3018-api-design-for-humans • http://broadcast.oreilly.com/2011/06/the-good-the-bad-the-ugly-of-rest- apis.html • http://sixrevisions.com/html/introduction-web-storage/ • http://webcomm.fiu.edu/2011/11/json-as-an-api-tool-and-why-its-awesome/ • http://doteduguru.com/id4579-results-higher-ed-cms-usage.html
- 67. Hackathons • http://dschool.stanford.edu/blog/2012/01/27/hack-d-kicks-off-more-than-a- dozen-projects-underway/ • http://civic.mit.edu/blog/schock/occupydata-hackathon-2-roundup • http://newmed.media.mit.edu/health-and-wellness-innovation-2012 • http://nyuad.nyu.edu/hackathon/about/ • http://startup.berkeley.edu/hackathon/ • http://www.njit.edu/hackathon/ • http://www.lib.umich.edu/art-architecture-engineering-library/ announcements/48-hour-mobile-app-hackathon
- 68. Questions? Don’t be shy.
- 69. Thank You @nickdenardis [email protected] http://nickdenardis.com/ https://speakerdeck.com/u/nickdenardis