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
- URIs 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!