If I'm ever going to understand Web Services, I'm going to have to build one. Herewith, a sketch of a service I plan to build.
If a little knowledge is dangerous, where is the man who has so much as to be out of danger?
I don't think it will surprise any of my colleagues if I reveal that I just don't “get” web services. I mean, I think I understand what “web services” means at a conceptual level:
We've got this nifty XML thing that allows us to markup our data.
We've got this nifty internet thing that let's a whole bunch of computers talk to each other.
We think there's money to be made from getting computers to talk to each other in a way that is unambiguous and conforms to business contracts.
We'd like to make it easy for programmers to write applications that use web services because that helps drive the whole enterprise (and there's probably money to be made in selling tools to programmers, too).
So let's combine them! Let's use XML to send data between computers on the internet (which we'll call the web) so that they can accomplish tasks (which we'll call services).
Ok so far?
To do this, we'll need
REST
and
SOAP
and
XML-RPC
and
WSDL
and WS-X, WS-Y,
and WS-Z. That looks like a whole lot of
acronyms for a concept that seems not too hard to grok. I
must be missing something.
Like most things, I don't think I'm really going to understand this stuff until I use it, so I'm going to build a web service. I've even figured out what it's going to be.
Where In The World
My web service is going to be called “Where In The World” (WITW) and it's going to expose two methods (addresses? service endpoints?): you'll be able to tell it “where I am” and you'll be able to ask it “where is someone”. I'll open the whole thing up so that anyone who's interested can play with it.
The “where I am” service for a given user will accept either a latitude and longitude or the name of a known landmark. (Eventually, there will have to be another method to add landmarks, but let's not worry about that now.) It'll remember where they said they were and when they said they were there.
The “where is someone” service will return the last known location of a given user. Optionally, it will provide a list of other users and landmarks that are or were nearby.
That seems like a not quite entirely trivial set of services that provides a read-only “get information” service (method? endpoint?) and a writeable “put information” service.
My plan is to support a RESTful API, a SOAP XML-RPC-style API, and a SOAP document-style API to the services (if I get ambitious, I may even provide an email API and a Fast Infoset or some other binary API). At least to the extent that I currently understand what those acronyms mean. I expect that I'll need to build at least one WSDL file to describe the services. Whether I'll need any of the other WS-mumble specifications remains to be seen.
Web service greasemonkeys, tell me, am I in the right ballpark? Have I outlined reasonable services? Do you think there's enough richness there to learn anything?
Comments:
One problem with this as a demo is that the way you've outlined it, it's not linky, and that means that you're handicapping REST by taking away one of its major benefits over RPC. A better demo would be one that handles several different kinds of related things that carry references to each-other (i.e. something that would make at least a tiny moderately-connected UML class diagram). The only opportunity I can see for linking in the current model is between users and landmarks. I'm guessing that you're planning on using a unique string (e-mail address? URL?) to identify users, rather than managing them as bona-fide objects.
(Bit off topic. About those unique ID attributes. The elements with the CLASS attribute applied to them do not have them.)
(Eventually, there will have to be another method to add landmarks,but let's not worry about that now.)
I wonder why this needs to be different from the "Where I am" function. Couldn't the landmark be the "I"? That would make for a nice simple API (I might be thinking too RESTian, though.)
Thanks, Anne, that's fixed now.
Yes, the "where am I" function could be overloaded to handle landmarks, I guess. Though I had in mind slightly different "parameters". For "where am I", I just need to provide some indication of who I am and a latitude and longitude. For the landmark, I might also want to provide a description and perhaps a URI.
Best of luck with this Norm, it looks to be a very informative experiment, and I for one will be following it closely.
Although it looks like you're going into this with a pretty open mind with the intention to learn rather than evaluate, I suspect that others will not necessarily feel the same way. I'm including myself here: I have a predjudice towards RESTful architectures (admittedly based on very little experience) and am expecting to see your RESTful API "win" in some sense.
Just something to be aware of, which you probably are anyway.
For that added complexity, how about letting a person or landmark have a set of properties? Then you could ask questions like "who of my collegues are currently reasonably close to work?" or "which mountaineers are currently up a peak?".
I'm a bit sceptical as to wether I would be interested in using the service, though ...
Interesting experiment! It would be cool if you could include features such as message level security (e.g. I'll email an encrypted message containing my location to some gateway) ...