API Reliability Guide

@nickdenardis / #psuweb12http://www.flickr.com/photos/erreeffe/3769670873/

Nick DeNardis

Associate Director of Web Communications at Wayne State Universityhttp://wayne.edu/

Host of EDU Checkuphttp://educheckup.com/

Curator of EDU Snippitshttp://edusnippits.com/

Writer for .eduGuruhttp://doteduguru.com/

DisclaimerSome assembly required.

APIApplication Programming Interface

Not just for robotshttp://www.flickr.com/photos/stevent/3241986538/

Value Chain

http://apigee.com/

The API’s job is to make the

developer as successful as

possible

http://knowyourmeme.com/memes/i-hate-sandcastles-success-kid

It makes the user experience

http://www.flickr.com/photos/daychokesnight/2149714792/

can break

Too slow...

http://www.flickr.com/photos/toolmantim/6170448143/

Too complicated...http://www.flickr.com/photos/toolmantim/6170448143/

Adds a layer

http://www.flickr.com/photos/jabb/6715983809/

Complications with mobile

“always on”

Mobile isn’t going anywhere

1.45 Million devices per day371,000 births per day

http://www.lukew.com/ff/entry.asp?1506

Mobile Data Traffic Expected To Rise 40-Fold Over Next Five Years

http://techcrunch.com/2010/03/30/mobile-data-traffic-rise-40-fold/

Mobile users use more bandwidth

250 kb - Avg page weight2.5 pages - Avg number per visit

625 kb - Bandwidth per visit

Desktop

50 kb - Avg page weight25 pages - Avg number per visit

1.25 mb - Bandwidth per visit

Mobile

0

325

650

975

1300

Data

Desktop Mobile

0

10

20

30

40

2009 2010 2011 2012 2013 2014 2015 2016 2017

Mobile Desktop

Millions of visitors

http://wayne.edu/

The mobile Web is slowAnd it’s mostly our fault

Time

Cell Latency

Initial HTML

Javascript

Images

CSS

You can’t blame the network for everything

Time

Cell Latency

New Content

Images

Second RequestFirst Request

Do less better

One size != fit all

Think versioning from the start

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.0https://api.wayne.edu/v1/

SOAPThe request:

GET /StockPrice HTTP/1.1Host: example.orgContent-Type: application/soap+xml; charset=utf-8Content-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:GetStockQuote> <s:TickerSymbol>IBM</s:TickerSymbol> </s:GetStockQuote> </env:Body></env:Envelope>

The response:

HTTP/1.1 200 OKContent-Type: application/soap+xml; charset=utf-8Content-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>

The request:

GET /StockPrice/IBM HTTP/1.1Host: example.orgAccept: text/xmlAccept-Charset: utf-8

The response:

HTTP/1.1 200 OKContent-Type: text/xml; charset=utf-8Content-Length: nnn

<?xml version="1.0"?><s:Quote xmlns:s="http://example.org/stock-service"> <s:TickerSymbol>IBM</s:TickerSymbol> <s:StockPrice>45.25</s:StockPrice></s:Quote>

REST

4 kb vs 2 kbRound Trip

Stick to REST

XML suckshttp://www.flickr.com/photos/philmanker/3654636770/

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

Existing Resources

http://doteduguru.com/id7800-results-higher-ed-cms-usage-survey-2011.html

Flattened highed = More interfaces

CRMCMS

iModulesEvents

Course ScheduleParkingFlickr

YouTubeFaculty ProfilesLibrary Catalog

Your data is everywhere

CMS

Events

LDAP

Banner

Gather & Clean

Shadow storage

API Webserver

Website

Mobile Website

Mobile App

Digital Signage

Third Party

API is the glue

CMS

Events

LDAP

Banner

Gather & Clean

Shadow storage

API Webserver

Website

Mobile Website

Mobile App

Digital Signage

Third Party

Rolling your own API

Trust no one.

Making the glue

Server space you controlapi.domain.edu or domain.edu/api

Ingredients:

Ability:

• Database• Cronjobs• Server logs• Analytics• PHP accelerator• Xdebug

Getting data closer

Documentation

Design

http://www.flickr.com/photos/edublogger/6950969837/

AffordanceThe physical design will communicate how it

is suppose to be usedhttp://www.flickr.com/photos/hawkexpress/269032594/

/getNews/getNewsReleases/findPeople/getPerson/eventsList/eventInfo/eventRSVP/classSearch/semesterList/parkingLotList/parkingAvailable

Create. Read. Update. Delete.

http://www.flickr.com/photos/fss/2181882493/

Read first.

http://www.flickr.com/photos/hackaday/4425372655/

GET /academic/colleges/listingGET /academic/colleges/info/150

REST

Category

Interface (Class)

Function

Item

GET /academic/colleges/listingGET /academic/colleges/info

GET /academic/majors/listingGET /academic/majors/info

GET /academic/classes/listingGET /academic/classes/info

GET /parking/availability/listingGET /parking/availability/info

The devil is in the details

Simple URL

Response code

Total count

Data container

Keep it lightweight

91 KB

Use only what you need

Filters

Less data

41 KB

Writing data

POST /admissions/rfi/addPOST /admissions/visit/addPOST /admissions/application/add

POST /academic/colleges/addPOST /academic/colleges/edit

POST /academic/majors/addPOST /academic/majors/edit

Post data:id=3047

Soft Delete(keep all the data!)

POST /academic/colleges/remove

POST /academic/majors/remove

POST /academic/classes/remove

POST /parking/availability/remove

Post data:id=3047

Authentication/api/user/auth

Auth workflow

Request API Key Rate Limit

Check Credentials

Username/Pass

Session ID

Session ID

(Do work) Return

Rate Limiting100 per minute per Key/IP

Cache. Cache. Cache.

Professional cache

http://www.flickr.com/photos/carlos/2417032795/

APC

<?php$bar = 'BAR';apc_store('foo', $bar);var_dump(apc_fetch('foo'));?>

Static Cache

http://www.flickr.com/photos/basic_sounds/5779597720/

Static files

<?phpif ((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);

?>

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/

HTML5 localStorage

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"]});

Expires header<?php header('Expires: '.gmdate('D, d M Y H:i:s \G\M\T', time() + 3600));?>

SemestersSubjectsDegreesMap CategoriesMap Locations

1 Month

CoursesMedia Experts

1 Week

Course AvailabilityParking Availability

No Cache

EventsNews

1 Day

Our Stats

Feb 2011 - In production6.1 million requests

48% from mobile21% iOS23% Android66% Web

95% GET’s16 ms average response time

Examples

Mobile news

Google APImaps/locations/listing

events/event/listing

directory/people/listing

academic/courses/listing

maps/category/listing

maps/location/info

events/event/listing

faculty/profile/info

go/url/info

HackathonCommunity through data

http://www.flickr.com/photos/hackny/5684887983/

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

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

Questions?Don’t be shy.

Thank You@nickdenardis

nick.denardis@gmail.comhttp://nickdenardis.com/

https://speakerdeck.com/u/nickdenardis