Supersedes WITW Part II: SOAP RPC, 18 Feb 2005.
WITW: SOAP RPC (V2)
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.
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.