In the previous posts of this series I developed a RESTful web service capable of supplying multiple representations. For this post I wanted to add one more representation… “help.” This representation should allow anybody developing a client for the web service to discover and experiment with its capabilities.
See the previous posts in this series for the story so far:
I could have simply added help text to the XHTML already returned by the web service. However, during normal usage, this would waste bandwidth, especially if the help was very detailed. I also wanted a way for a new client developer to experiment with the web service, beyond using the read only GET verb that the browser normally uses… I wanted to provide a simple test harness.
In the Site.Master I added an ASP.Net panel that is only shown if the requested format is “help”. A test of the format Query String variable determines whether to display the panel:
private bool HelpEnabled
bool helpEnabled = false;
string format = this.Request.QueryString["format"];
if ((format != null) && (format.Equals("help", StringComparison.OrdinalIgnoreCase)))
helpEnabled = true;
The framework put in place to support a “help” representation means a developer of an ASPX pages can explain how to use that part of the service within the same file that renders that service’s XHTML output. Hopefully this will mean the documentation is kept up to date!
This version of the source can be downloaded:
My next post will look at using HTTP Status Codes with the web service. I haven’t looked into this yet, so there may be a slight delay!