8 24 2005-02-16T09:16:29-05:00 $Date: 2005-09-11 10:27:02 -0400 (Sun, 11 Sep 2005) $ NormanWalsh 2005Norman Walsh 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.]

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: Norman Walsh http://norman.walsh.name/ 9f5c771a25733700b2f96af4f8e6f35c9b0ad327 ]]> 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: http://norman.walsh.name/2005/02/witw/is/ndw?nearby=0 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: http://norman.walsh.name/2005/02/witw/is?userid=ndw&nearby=0

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: 37.7667 -122.4167 ]]> 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: Logon International Airport ]]> 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): ]]> The replies are XML documents that conform to this schema (in XSD, if you prefer).

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.

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.