A short presentation on how you might like to build a simple “Web API“.

Updated: an accessible version with errata fixes and links:

A Web Friendly API ? Javascript AJAX Python Ruby PHP Perl Curl [Picture: collection of Web 2.0 logos from flickr, Google, Yahoo!, last.fm, etc] One thing in common .. They HATE SOAP But LOVE The Web URI s identify stuff And can be anywhere [photo of shower head with URI WWW.SPEAKERMAN.COM ] Use cool URIs Read RFC 2616 Constrain Verbs: GET /HEAD and POST (PUT, DELETE, OPTIONS – YAGNI ?) Ask “IS IT SAFE ?” [photo of the dentist from Marathon Man] Understand HTTP Methods: method safe idempotent semantics resource cacheable ----------------------------------------------------------- GET | X X X X X | HEAD | X X X X X | PUT | X X X | POST | * | DELETE | X X X | OPTIONS | X X X | ----------------------------------------------------------- PROPFIND | X X X X * | PROPPATCH | X X X | MKCOL | * X X | COPY | X X X | MOVE | ? X X | LOCK | X X | UNLOCK | X X X | PATCH | * X X | ----------------------------------------------------------- think about representations: HTML, RSS /Atom, XML, JSON, whatever Warning! You are about to see Naked Protocol Headers! Content-Negotiation: HTTP GET ... Accept: application/weatherml+xml; q=1.0, application/xml; q=0.8, text/html; q=0.5 Apache Server .htaccess AddType application/weatherml+xml wea Options +MultiViews ./index.wea ./index.xml ./index.html enjoy the free caching HTTP GET http://flickr.com/photos/psd/2450160 If-Modified-Since: Fri, 31 Dec 1999 23:59:59 GMT If-None-Match: 'guid-21343244324' HTTP/1.1 304 Not Modified make Phone Call HTTP POST http://example.com/calls Content-Type: application/x-www-form-urlencoded Accept: text/xml; charset=utf-8 callingParty=tel:+447918808 calledParty=sip:Merlin => HTTP 1.1 201 Created Location: http://example.com/calls/123213 Content-Type: text/xml; charset=utf-8 <callInfo> <callId>http://example.com/calls/123213</callId> <callStatus>Initial</callStatus> </callInfo> get Call Info HTTP GET http://example.com/calls/123213 Accept: text/xml => 200 OK Content-Type: text/xml; charset=utf-8 <callInfo> <callId> http://example.com/user/fred/calls/123213 <callStatus> CallInitial <callingParty> tel:+447918880... <calledParty> tel:+447918880... <timeStarted> 2007-01-09 11:45:20 <duration> 502 <terminationStatus> CallNotTerminated </callInfo> end Call HTTP POST http://example.com/calls/123213 Content-Type: application/x-www-form-urlencoded callStatus=Terminated => 202 Accepted Location: http://example.com/calls/123213 list Recent Calls [Feed Icon] HTTP GET http://example.com/calls/feed => 200 OK Content-Type: application/atom+xml <feed xmlns="http://www.w3.org/2005/Atom"> <title>Phone Calls <link rel="self" href="http://example.com/calls/" rel="alternate" type="text/html"/> <updated>2007-01-0911:45:02Z <author><name>Phonebox <id>tag:example.com,2007-01-09:/calls <entry> <link href="http://example.com/user/psd/calls/1234567/"/> <title>Call 1234567 <id>tag:example.com/calls/1234567-200701091223313 <summary>CallInformation <updated>2005-10-13T18:30:02Z </entry> <entry> <link href="http://example.com/user/fred/calls/17231667/" ...

Overall: http://example.com/calls http://example.com/calls/feed http://example.com/user/paul/calls/feed http://example.com/user/paul/calls/7d6374da5 http://example.com/user/paul/calls/search?callingParty=tel:%3A44791888 http://example.com/sms http://example.com/sms/feed http://example.com/user/fred/sms/7d6374da5 http://example.com/user/fred/sms/inbox/feed http://example.com/user/fred/sms/inbox/7d6374da5 http://example.com/user/fred/sms/inbox/search?from=tel:%3A44791888 .... Yes, Dear Reader, there’s no API as such it’s just yet another Web site .. Surf long and prosper!

Technorati Tags: HTTP, REST, webarch