Supersedes WITW Part II: SOAP RPC, 18 Feb 2005.

WITW: SOAP RPC (V2)

Volume 8, Issue 32; 24 Feb 2005; last modified 08 Oct 2010

A revised SOAP RPC interface.

I've revised my second interface to Where In The World. It's still a set of methods that you can invoke using SOAP RPC, but I've changed the methods so that they all return simple, scalar values. I'm not sure I understand how SOAP is supposed to return arrays and I'm sure I don't understand how to do it in WSDL. So the salient bits are now:

The target SOAP node

That's “http://norman.walsh.name/2005/02/soap/witw” (Note the change: it's “/soap/witw” where it used to be “/witw/soap”. Sorry, I know that's confusing; it's more fiddling to do with authentication that's just not important today.) That URI is for the “where is someone” services. I'm not going to re-implement the “where I am” services in SOAP unless someone actually tells me they want to use them.

The namespace of the services

That's “http://norman.walsh.name/witw”. I'd have made that a dated URI, but I'm using Perl’s SOAP::Lite module to do the implementation and there was some weirdness in the way that the namespace name was mapped to the Perl module name. I decided to just punt.

The names of the methods

They are “name”, “email”, “uri”, “latitude”, “longitude”, and “date” described below.

I've decomposed things differently again to to make all the methods return simple scalars.

Name

The name method returns the full name of the person associated with a userid:

xs:string name(xs:string userid)
    throws UnknownUser;

It returns the full name of the user.

If the specified userid is unknown, the service faults.

Email

The email method returns the email address of the person associated with a userid:

xs:string email(xs:string userid)
    throws UnknownUser;

It returns a hash (in the mbox_sha1sum-style of FOAF) of the user's email address.

If the specified userid is unknown, the service faults.

Uri

The uri method returns the URI of the person associated with a userid:

xs:string uri(xs:string userid)
    throws UnknownUser;

It returns the URI associated with a user.

If the specified userid is unknown, the service faults.

Latitude and Longitude

The latitude and longitude methods returns information about the location of the specified userid.

xs:float latitude(xs:string userid)
    throws UnknownUser, UnknownLocation;

xs:float longitude(xs:string userid)
    throws UnknownUser, UnknownLocation;

These methods return the latitude and longitude of the specified user, respectively.

The methods fault if the userid is unknown or if the user has not specified a location.

Date

The date method returns the when the position of the user was last updated.

xs:dateTime date(xs:string userid)
    throws UnknownUser, UnknownLocation;

It returns the date and time of the last time that the users position was updated.

The method faults if the userid is unknown or if the user has not specified a location.

Sample Code

On the assumption that any who's read this far won't be scared off by a few lines of code, here's a short Perl script that returns the latitude and longitude of a user.


      #!/usr/bin/perl -- # -*- Perl -*-

use strict;
use SOAP::Lite;

my $usage = "$0 userid\n";

my $userid = shift @ARGV || die $usage;

my $soap = SOAP::Lite->new();
$soap->uri("http://norman.walsh.name/witw");
$soap->proxy("http://norman.walsh.name/2005/02/soap/witw");

my $result = $soap->name($userid);
if ($result->fault()) {
    print STDERR "SOAP fault: ", $result->faultcode(), "\n";
    print STDERR "\t", $result->faultstring(), "\n";
    exit 1;
}
my $name = $result->result();

$result = $soap->latitude($userid);
if ($result->fault()) {
    print STDERR "SOAP fault: ", $result->faultcode(), "\n";
    print STDERR "\t", $result->faultstring(), "\n";
    exit 1;
}
my $lat = $result->result();

$result = $soap->longitude($userid);
if ($result->fault()) {
    print STDERR "SOAP fault: ", $result->faultcode(), "\n";
    print STDERR "\t", $result->faultstring(), "\n";
    exit 1;
}
my $long = $result->result();

$result = $soap->date($userid);
if ($result->fault()) {
    print STDERR "SOAP fault: ", $result->faultcode(), "\n";
    print STDERR "\t", $result->faultstring(), "\n";
    exit 1;
}
my $date = $result->result();

$lat = sprintf("%2.2f%s", abs($lat), $lat > 0 ? "N" : "S");
$long = sprintf("%2.2f%s", abs($long), $long > 0 ? "E" : "W");

print "$name was last seen at $lat, $long.\n";
print "That was on $date.\n";

    

This evening, if you pass it ndw, it tells you I'm at home:

$ perl witw.soap.pl ndw
Norman Walsh was last seen at 42.34N, 72.45W.
That was on 2005-02-21T21:05:16Z.

The brute force API still works the same way.