Thursday, November 08, 2007

Free Web Services

So, every once in a while I'll run into a programming conundrum in something I'm working on and either wish there was something I could download and implement fairly quickly or that there was a web service hanging "out there" that I could hook in to.

Well, I guess I'm going to start my own set of web services and leave them hanging "out there" for me to use, and anyone else who is brave enough to use something they are not hosting themselves. I'll be hosting it on my forthcoming company website at the following urls:

Yes, I'll be providing both soap and json interfaces. The soap interface is generally useful in standard web services calls, although to implement into your own AJAX-based website or webapp you'll have to write a proxy running on your site which will then access this web service.

Not so with the json interface, though. All you'll need to do is include the json url in your web page using a script tag and the proper querystrings to call the function you want, and the service will call back the function of your choice (specified in the querystring) and pass in the requested data as a parameter.

While the jsoninterface doesn't include it's own description page, if you click the soap url above you'll find information on how to call each method using soap. When consuming a web service in the .Net environment you generally get a nice class and set of methods to call from the web service -- the Intellisense kicks in and shows you the parameters you need to pass in a what-not. Not sure how it works in other environments.

For the json calls you'll have to specify the "op" and "cb" querystrings manually for each method you call. The "op" is short for operation and is the name of the method. "cb" is short for "callback" and is the name of the function you want the server to call back when it's done. For instance, when calling the "GetGuid" method (details on this method forthcoming) you will set "op" to "GetGuid", and if you want the server to call back your javascript method called "procGuid" after it's generated, you would set "cb" to "procGuid". Therefore, the whole tag would look like this:
<script type="text/javascript" src=""></script>
If either of those parameters are omitted then an error is thrown by using an alert. Other parameters may be required on a per method basis.

The data returned from both interfaces will formatted in a similar fashion. The packet will be in two pieces, an "error package" and a "data package" encapsulated inside a "return package." You can actually see this arrangement if you run the GetGuid method through the soap url or pasting the value of the src parameter from the above script tag in your browser address bar.

The error package will always contain the following pieces of information:
  1. Flag. This will either be True or False, indicating if an error occurred.
  2. Message. The error message.
  3. StackTrace. The stack of methods called leading up to the error. Probably not very useful to you, but useful to me in figuring out the problem.
  4. AdditionalInfo. This may contain any other useful tidbits I stuffed in there before pushing everything back to the browser.
The contents of the data package will vary. I'll try to include detailed information for each method. I have a few more idea for new methods that I'll work on at some point, and requests for new methods are also welcome.

Lastly, in the event that these services gather any traction, I'll try to keep all related posts tagged with the "lpsws" label.


No comments: