WhatfettleWeb APIs Are Just Web Sites

Warning

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

Updated: an accessible version with errata fixes and links:

  1. A Web Friendly API?
  2. Javascript AJAX Python Ruby PHP Perl Curl
  3. [Picture: collection of Web 2.0 logos from flickr, Google, Yahoo!, last.fm, etc]
  4. One thing in common ..
  5. They HATE SOAP
  6. But LOVE The Web
  7. URIs identify stuff
  8. And can be anywhere
  9. [photo of shower head with URI WWW.SPEAKERMAN.COM]
  10. Use cool URIs
  11. Read RFC 2616
  12. Constrain Verbs: GET/HEAD and POST (PUT, DELETE, OPTIONS - YAGNI?)
  13. Ask "IS IT SAFE?" [photo of the dentist from Marathon Man]
  14. 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                  | 
                 ----------------------------------------------------------- 
    
  15. think about representations: HTML, RSS/Atom, XML, JSON, whatever
  16. Warning! You are about to see Naked Protocol Headers!
  17. 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
    
  18. 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
  19. 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>
    
  20. 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>
  21. 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
  22. 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/" 
        ...
  23. 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
    
    ....
  24. Yes, Dear Reader, there's no API as such it's just yet another Web site ..
  25. Surf long and prosper!

Technorati Tags: , ,