Creating a RESTful Web Service Using ASP.Net MVC Part 4 – Help Representation

October 8, 2008 00:27 by admin

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

{

    get

    {

        bool helpEnabled = false;

 

        string format = this.Request.QueryString["format"];

        if ((format != null) && (format.Equals("help", StringComparison.OrdinalIgnoreCase)))

        {

            helpEnabled = true;

        }

 

        return helpEnabled;

    }

}

Within the help panel there is a ContentPlaceHolder that the current ASPX page can use to inject any help text specific to the controller action being called. Below the place holder is some JavaScript and HTML form elements. Together these provide a simple test harness for the web service:

Help Representation

You set the URI, representation and any content in the test harness. Then press one of the buttons to submit the request (the different buttons dictate which HTTP verb is used). The JavaScript uses an XMLHttpRequest object to submit the request. The test harness allows you to experiment with requesting the different representations available… all from your browser, without writing a client of your own.

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!

kick it on DotNetKicks.com


Comments (1) -

December 21. 2010 13:47

Kim

Interesting post, I see now, what is your point. Thank you for pushing that into my mind!

Kim

Add comment

  Country flag

biuquote
  • Comment
  • Preview
Loading