Simply exchanging XML documents over HTTP.

Let's call my first attempt at Where In The World the “brute force and ignorance” approach. I want to provide “where is” and “where I am” functionality over the web. Starting from first principles, web services communicate by exchanging XML documents over the web, so that's what these functions do. For now, “the web” will mean HTTP.

[Update: I've changed the schemas since this essay was published, see WITW Extensibility and Versioning for more details.]

Where Is Someone? 

Give this service an identifier and it tells you the last reported location of that identifier. This service just looks and smells like an HTTP GET to me:

wget http://norman.walsh.name/2005/02/witw/is/ndw

ought to tell you where I am. And indeed it does:

  1$ wget -q -O - http://norman.walsh.name/2005/02/witw/is/ndw
  2<?xml-stylesheet type='text/xsl' href='/style/witw-is.xsl'?>
  3<is xmlns='http://nwalsh.com/xmlns/witw-is#'
  4    date='2005-02-16T12:36:51Z'>
  5<user userid='ndw'>
  6<name>Norman Walsh</name>
  7<uri>http://norman.walsh.name/</uri>
  8<foaf:mbox_sha1sum xmlns:foaf='http://xmlns.com/foaf/0.1/'>9f5c771a25733700b2f96af4f8e6f35c9b0ad327</foaf:mbox_sha1sum>
  9</user>
 10<locations>
 11<location lat='42.3382' long='-72.45' date='2005-02-15T13:31:59Z'/>
 12</locations>
 13<landmarks>
 14<landmark name="The Travel Loft" lat='42.3812' long='-72.5204' dist='4.67' units='mi' uri="http://travelloft.biz/" />
 15</landmarks>
 16</is>

The replies are XML documents that conform to this schema (in XSD, if you prefer).

I said that the list of “nearby landmarks” would be optional, so that URI also supports parameters. You can add, for example, “?nearby=0” to turn off the list:

And if it turns out to be inconvenient in your programming API to represent the user id as path information, you can make it a parameter instead:

Where I Am 

This service is a bit trickier. For one thing, I don't want miscreants out there to be able to move people around like pawns on some roughly spherical chess board. That means I need some sort of security.

The simplest thing that occurs to me is HTTP basic authentication. Simple is good, so I'm going to use that for now. I should also use https: but that requires certificates and things that don't seem quite so simple, so I'm not going to worry about that right now.

The rub, of course, is that in order to use basic authentication, you have to have user ids and passwords on the web server. In anticipation of the enormous popularity of this service (not!), I don't want to be maintaining that by hand. On the plus side, I already need some sort of identifier for the “where is someone” request, so I can solve both problems at the same time, I guess.

If you walk through a simple registration procedure, you too can have a user id for the WITW services and you'll also have a password to get into the WITW realm for publishing where you are.

Ok, with security out of the way, let's turn our attention back to the web service. What does the service need? It needs to know who I am and my latitude and longitude. Authentication will provide my user id, so all I really need to send is my location:

  1<location xmlns="http://nwalsh.com/xmlns/witw-post#">
  2<latlong>
  3<lat>37.7667</lat>
  4<long>-122.4167</long>
  5</latlong>
  6</location>

You do know the latitude and longitude of every city and place on earth, don't you? You don't? Uhm, ok, let's give you the option of specifying your location by landmark instead:

  1<location xmlns="http://nwalsh.com/xmlns/witw-post#">
  2<landmark>
  3<name>Logon International Airport</name>
  4</landmark>
  5</location>

Better? Maybe. Now you have to know what landmarks the service knows about, but I've already said we'll worry about that later. In short, you can update your location by doing an HTTP POST to http://norman.walsh.name/2005/02/witw/ami/now sending a document that conforms to this schema (in XSD, if you prefer):

  1wget -q -O - --http-user ndw --http-passwd PASSWORD --post-file /tmp/loc.xml \
  2     http://norman.walsh.name/2005/02/witw/ami/now
  3<ami xmlns='http://nwalsh.com/xmlns/witw-ami#' date='2005-02-16T13:03:55Z'>
  4<user userid='ndw'/>
  5<location date='2005-02-16T13:03:55Z' lat='42.3382' long='-72.45'/>
  6</ami>

The replies are XML documents that conform to this schema (in XSD, if you prefer).

Symmetry 

Now I have two addresses that the world can interact with to perform actions. I think those are Web Services, at least in a broad sense. But I'm troubled by the lack of symmetry. You can GET from one and POST to the other. I don't know if it's proper web services architecture or not, but I decided to support both operations on both addresses.

To that end, you can retrieve a location by doing a POST to the http://norman.walsh.name/2005/02/witw/is address. Your request must conforms to this schema (in XSD, if you prefer).

And if you do a simple GET on the http://norman.walsh.name/2005/02/witw/ami/now address, you'll get back an HTML form that you can use to do the POST, which seems quite convenient.

Next Steps 

I think I've got a couple of web services now. I wouldn't claim they've really been “tested” exactly, but I've used them once or twice. The schemas a pretty ugly, I should probably clean those up a bit. And there are no WSDL files or other machine readable descriptions of the APIs, I should probably work on that.

In the meantime, comments most welcome. Several people commented on the first essay offering suggestions for extensions. I might get to those eventually, but baby steps first, I think. Besides, adding them later will let me experience the joys of schema evolution and versioning.

Comments:

Your Where In The World link at the top is broken. It's pointing at Feb 16 instead of Feb 15.

Posted by Jeffrey Yasskin on 16 Feb 2005 @ 05:28pm UTC #

Oops. That's what I get for starting an essay on one day and finishing it on the next. Fixing now, thanks.

Posted by Norman Walsh on 16 Feb 2005 @ 05:38pm UTC #

Okay, the system is now tracking me; my id is "johnwcowan".

Posted by John Cowan on 17 Feb 2005 @ 04:44am UTC #

I'm just curious why your are using hash at the end of namespace URI:
http://nwalsh.com/xmlns/witw-ami#
It is to prevent users to write it with trailing slash which will change URI and namespaces will stop to work? I recall that such syntax was used in RDF and I see it more and more often.

Posted by Jirka Kosek on 17 Feb 2005 @ 08:18am UTC #

I'm subscribed to WITW as SHE.

Posted by Sina on 17 Feb 2005 @ 02:47pm UTC #

Finding lat and long? http://www.geobytes.com/IpLocator.htm?GetLocation is very helpful if you know an ip address of a server nearby! And with your readership Norm, I guess thats likely? HTH DaveP.

Posted by Dave Pawson on 18 Feb 2005 @ 01:08pm UTC #

The MultiMap (http://www.multimap.com/) server will provide a latitude and longitude for any address.

Posted by Norman Walsh on 18 Feb 2005 @ 01:22pm UTC #

Shouldn't the service use the person as a resource, not as a service endpoint? Imagine that URI: http://norman.walsh.name/2005/02/witw/location/ndw Now I can GET the location, or POST the location directly onto that resource. Wouldn't that be more RESTful?

Posted by Michael Jakl on 18 Feb 2005 @ 06:53pm UTC #

Nice comment by Michael Jaki, to further indulge if that was feasible then you could also put in place an ESB container over the top as well as perhaps have the future opportunity to use XPath to query the CoPML file of the URI. CoPs and P2PSN: http://www.openpeople.info/index.php/WOW/CommunitiesOfPractice

Posted by Ed Daniel on 21 Feb 2005 @ 06:00pm UTC #
Comments on this essay are closed. Thank you, spammers.