Resources Over MVC – Providing Help

November 19, 2011 21:35 by Admin

The Resources Over MVC (ROM) assembly allows your RESTful web service to serve multiple representations. Out of the box it supports JSON and XML. One advantage of creating a web service using ASP.Net MVC rather than Windows Communication Foundation (WCF) is that you also get great support for serving XHTML as another representation. This allows a developer to investigate your web service with their browser. In this post we’ll look at providing help (and a test harness) for the client developer directly within the web service.

When using the ROM assembly (see the earlier post) one of the default handlers that is registered is the XhtmlFormatHandler which uses the standard ASP.Net MVC mechanisms for rendering a resource. So long as you provide standard views (razor or web form based views) and they generate XHTML then you will now be supporting XHTML as well… at least read only! This means the web service can be navigated using a standard web browser.

“Help” is an additional representation you can add to your web service that doesn’t make much use of the ROM assembly, mainly just the standard ASP.Net MVC framework. The XhtmlFormatHandler will additionally handle requests were the AcceptTypes is “help” (which can be set in either the header or on the URI if you are using the MapRomRoute extension.

In sample, the following was added:

  • A Menu tab that toggles Help on and off by appending format=help to the URI
  • An area in the _Layout.cshtml file (this would be the Master file in a web forms based site) that is toggled on and off depending on whether the current format is “help”
  • Within the toggled section there is a simple JavaScript based client that can be used to call the web service
  • A render section within the toggled area that Views can populate with additional, context specific, help text

So adding help just uses the normal ASP.Net MVC framework, but having it as part of your web service (rather than separate documents) means it is more likely to be kept in step with the web service. It is also always available to the client developer and with a test harness built in, they can also experiment with the web service directly. The View specific help can contain whatever you want but examples of useful content are:

  • Descriptive text
  • Sample URIs that actually work and are relative to the current context
  • Links to schemas (both XSDs and JSON Schemas)
  • Descriptions of supported methods (e.g. does this resource support PUT, POST etc.)
  • Details of the common Error Codes that might be returned from this resource

With this in place a client developer can navigate around the web service seeing pages like this:


Then click the “Show Help” tab to see a view like this:


The sample is available here: (4.5 mb)

Add comment

  Country flag

  • Comment
  • Preview