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.