Providing a Public API

Marc Tobias Metten

Lokku Ltd.

HTML output

JSON output

"response" : {
    "created_http" : "Mon, 07 May 2007 12:00:44 GMT",
    "created_unix" : 1178539244,
    "link_to_url" : "http://www.nestoria.es/palma-de-mallorca/casa/alquiler/num_res-20",
    "listings" : [
      {
        "bathroom_number" : 2,
        "bedroom_number" : 2,
        "datasource_name" : "Atrea",
        "keywords" : "Furnished, Attic",
        "latitude" : 39.5366,
        "lister_name" : "Alfa",
        "lister_url" : "http://rd.nestoria.es/rd?l=api-sr-title-1&sc=1-13946&url=1-U2FsdGVk....",
        "listing_type" : "let",
        "longitude" : 2.71594,
        "price" : 750,
        "price_currency" : "EUR",
        "price_formatted" : "750 EUR",
        "price_type" : "monthly",
        "property_type" : "flat",
        "summary" : "Bonito atico en las maravillas nuevo a estrenar, vistas al mar y...",
        "thumb_height" : 60,
        "thumb_url" : "http://limg.nestoria.es/c/3/c32295a2a0251437bd9981a0633158aa.jpg",
        "thumb_width" : 60,
        "title" : "Piso de 2 habitaciones en alquiler"
      },
    ]
    "attribution" : {
          "img_url" : "http://static.nestoria.es/i/realestate/es/es/pb2.png",  
          "img_height" : 20,
          "img_width" : 199,
          "link_to_img" : "http://www.nestoria.es",
    }
  

Different kinds

• non HTML-representation of data
  • XML, RSS, ...
• notification
  • ping, trackbacks
• submit/store/manage data
  • calendar [1], photos [2], files [3], user profile [4]
• transactions
  • ebay [5]
• transformation
  • translation, term extraction (WebService::Yahoo::TermExtractor)
  • conversion (geocoding) ...

Cool APIs

• Ecourier API
  • GPS position/speed/bearing of every driver
  • by type (motorbike), since 2004, 10sec resolution
• Graphmagic API
  • get a pie chart (image file)
• Yahoo! Maps
  • get a rendered map as PNG
• ReCaptcha API
  • get captcha HTML and session id
  • check if solved

REST Definition

• strict: "REpresentational State Transfer"
• loose: REST-style webservice over HTTP

REST Overview

RESTful web services

• Resource => unique address (e.g. URI)
• Request => HTTP (e.g. method GET)
• Response => HTTP (e.g. body XML)
• more layers => e.g. caching

Perl - Resource

    use URI;

    my $url = URI->new('http://api.nestoria.co.uk/api');
    $url->query_form(
         action        => 'search_listings',
         encoding      => 'json',
         pretty        =>  1,

         listing_type  => 'buy',
         property_type => 'flat',
         place_name    => 'Greenwich',
         bedroom_min   => 2,
         bedroom_max   => 2,
    );
    
    ##
    ## http://api.nestoria.co.uk/api?action=search_listings&encoding=json&pretty=1...
    ##

Perl - Request

    use LWP::Simple;
    
    my $response_json = get($url->as_string());

Perl - Response

    use JSON::XS;
    
    my $response      = from_json($response_json);

    printf("found %d results near %s\n\n",
         $response->{response}{total_results},
         $response->{response}{locations}->[0]->{title}
    );
    my $ra_listings = $response->{response}{listings};

    foreach ( @$ra_listings ){
         printf("%-50s | %12s | %.5f, %.5f\n",
             $_->{title},
             $_->{price_formatted},
             $_->{longitude},
             $_->{latitude},
         );
    }

Perl - Response formatted

found 324 results near Greenwich

2 bedroom flat for sale                            |  269,995 GBP |  -0.02161, 51.47150
Gainsborough House, Canary Wharf, E14              |  385,000 GBP |  -0.02188, 51.49850
3 Millennium Drive                                 |  399,950 GBP |  -0.00632, 51.49200
Discovery Dock East, E14                           |  800,000 GBP |  -0.02336, 51.49770
March Wall, Isle Of Dogs,, E14                     |  349,995 GBP |  -0.02468, 51.50040
Dunstable Ct, 12 St. Johns Pk, Blackheath          |  275,000 GBP |   0.01452, 51.47450
Flat for sale, E14                                 |  435,000 GBP |  -0.02651, 51.49140
2 bedroom flat to buy                              |  320,000 GBP |  -0.02301, 51.47250
Wheel House, Burrells Wharf, Isle Of Dogs, E14     |  442,000 GBP |  -0.02095, 51.48680
Pan Peninsula, E14                                 |  635,000 GBP |  -0.01320, 51.49930
Fergusons Wharf, 214 Westferry Road                |  320,000 GBP |  -0.01803, 51.48770
Westferry Point/ 156 Westferry Road, E14           |  335,000 GBP |  -0.01803, 51.48770
Nova Building, Odyssey, E14                        |  465,000 GBP |  -0.02791, 51.49230
River View Court, Old Bell Gate, E14               |  375,000 GBP |  -0.02783, 51.49410
Becquerel Court, W. Parkside, SE10                 |  399,995 GBP |   0.00687, 51.49710
Flat for sale, New Cross                           |  175,000 GBP |  -0.03709, 51.47990
2 bedroom flat for sale                            |  320,000 GBP |  -0.02371, 51.48960

The Resource

• uniquely addressable
• e.g. flickr photo
  • http://flickr.com/photos/babykailan/243139518/
  • http://flickr.com/photos/babykailan/sets/72157594200489503/
  • http://nestoria.co.uk/clapham/property/buy/bedrooms-2/maxprice-500000
  • http://tagzania.com/near/52.5166667/13.4/2950159/Berlin
  • http://tagzania.com/user/rprakash25

The Request

• URI
  • http://[host]/api/[resource-path]/[method-name].[response-format]
• HTTP methods
  • GET, HEAD
  • POST, PUT, DELETE
  • WebDAV adds: MKCOL, COPY, MOVE, LOCK...
• state information
  • URI parameters ( [resource-path]?set_readable=1 )
  • HTTP headers (e.g. Ebay API)

The Response

• text/xml
  • application/rss+xml (xml schema)
  • application/atom+xml
  • application/vnd.google-earth.kml+xml
• application/json - serialized Javascript
• text/javascript - with callback
• application/php - serialized PHP