MVC.ApiExplorer

The easy way to make people understand your APIs quickly.

screenshot

Introduction

Are you a developer who develops RESTFul service with ASP.NET MVC? Have you ever created some new actions and just want a convenient way to make sure that whether your actions are working well or not? The MVC.ApiExplorer is just for you.

MVC.ApiExplorer is a portable, independent component designed to help you explore all actions of controller in an ASP.NET MVC project. It doesn't do the things that unit testing or QA tools would do, so you can still use unit test tools in the development stage. However, when you are cooperating with someone else who develops another part of system that will invokes your API, such as frontend JavaScript or flash, MVC.ApiExplorer may help your partners understand your API quickly.

MVC.ApiExplorer automatically generates a test page which will lists all your actions of controller. Then you can do some test directly on the page. It is an easy, efficient way to save your time and life. All you need to do is add a reference of MVC.ApiExplorer to your project and create a page to explore your API.

Requirements

Get the source code

Since MVC.ApiExplorer is an open source project released under GPL 2 licence. You can checkout the source code here (Mercurial repository).

In case of you are not interested in the source code and just want to get benefit from using the useful tool. You can simply download the binary file or install it by nuget.

Getting started

It is really simple to install the MVC.ApiExplorer component to your project. Just follow the steps below.

Step1: Add reference of MVC.ApiExplorer.dll in your project.

Step2: Add an action - "ApiTest" for exploring all actions of controller. The action name "ApiTest" can be whatever you want. That just a example in this demo case.

Step3: Add a view of "ApiTest". In the view, you don't have to do anything but put just one line of code in it to render "Explore" action and specify which controller you want to explore on. The example code is below.

@{Html.RenderAction("Explore", "ActionExplore", 
	new { controllerType = typeof(The.controller.you.want.to.explore.HomeController) });}

Step4: Add exclusive MapRoute for ApiExplorer. That can avoid some problems which will occurs when ApiExplorer doesn't matches any route in the route table.

routes.MapRoute(
	"ApiExplorer",
	"ActionExplore/Explore",
	new { controller = "ActionExplore", action = "Explore" },
	new[]{"MVC.ApiExplorer"}
);

All steps are there. To get more understand. Please download the source code and check out how MVC.ApiExplorer works in the demo project.

How to use it

Run your project and navigate to "ApiTest". You will find that all your actions of HomeController have been displayed on ApiTest page. You can even specify all paraments and invoking method of each action to test it. Once you hit the "Invoke" button. The result of the action will be displayed in result area. That way you can easily see what will a client get when it invoke to your API.

Advanced

How to avoid redundant actions

If there are some actions you don't want to explore. You can decorate those actions with NonApi attribute then those actions wont be displayed on ApiTest page.

For example:

[NonApi]
public ActionResult Index()
{
	return View();
}

Display description of actions

You can decorate action with Description attribute to give a little information about what your API for. MVC.ApiExplorer will displays the description on the test page.

[Description("Get the data from our service. It will requires a key.")]
public ActionResult GetData(string key)
{
	//Do something here...
	return Json(new{Success=true, Data = data});
}

Additionally, you can also add a description for parameters.

public ActionResult GetData([Description("A valid key should be formated as xxx-xxx-xx")]string key)
{
	//Do something here...
	return Json(new{Success=true, Data = data});
}

Put the test page in an area

Sometime you want to put the test page in an area. Since RenderAction method will looks for ActionExplorerControler in the area where it belongs to. Certainly, ActionExplorerControler isn't here. That can cause an exception be throw out. So that you have to set the area as empty string to avoid that.

@{Html.RenderAction("Explore", "ActionExplore", 
	new { area="", controllerType = typeof(The.controller.belong.to.an.area.Default1Controller) });}

Specify a route name for your APIs

Assume that you have registered an exclusive route for your api which named "TheRouteForAPI" and registered "Other" route for other usage. Obviously, there is a collision between two of routes.

public static void RegisterRoutes(RouteCollection routes)
{
	routes.MapRoute(
		"Other",
		"{controller}/{action}/{id}",
		new { controller = "Other", action = "Index", id = UrlParameter.Optional },
		new string[] { "namespace.of.other.Controllers" }
	);

	routes.MapRoute(
		"TheRouteForAPI",
		"api/{action}",
		new { controller="API", action = "Api" }
		new string[] { "namespace.of.api.Controllers" }
	);

	......
	...........
}

By default, MVC.ApiExplorer will automatically looks for first matched route to generates Action url. It might does the right thing or it doesn't. In this case, the other route will be picked. However, you can specify a route name where your api will applies to. Just simply add a "routeName" attribute when you render the Explore action.

@{Html.RenderAction("Explore", "ActionExplore", 
	new { routeName="TheRouteForAPI", 
	controllerType = typeof(The.controller.you.want.to.explore.HomeController) });}

Display multiple controller in one test page

Don't do that.

MVC.ApiExplorer is not designed to works like that. If you have more then one controller to display. Make new test pages for each of them. There is a simply rule. One controller one test page.

Disable MVC.ApiExplorer after application has been deployed to server

MVC.ApiExplorer gives you a hand in the phase of development. You may however want to disable it when your application has been deployed to production server. It's easy. Just add a condition to the test page.

@{
	if (Context.IsDebuggingEnabled) 
	{
		Html.RenderAction("Explore", "ActionExplore",
		  new { controllerType = typeof(The.controller.you.want.to.explore.APIController) });
	} 
	else 
	{ 
		@:System is running.
	}
}

And remember to set Web.config correctly to make sure that your server doesn't run on debug mode. (Which people usually do not run debug mode on a production server)

.......
....
<system.web>
<compilation debug="false" targetFramework="4.0">
	<assemblies>
	<add assembly="System.Web.Abstractions, Version=4.0.0.0, Culture=neutral, PublicKeyToken=...." />
	<add assembly="System.Web.Helpers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=..." />
	......
	.........

Then the test page will not be displayed. Instead, just a short message "System is running." will be left on screen.

Known issue

When your action returns a result of JSON content. In Firefox browser, it will opens a download window to download the JSON document instead of displaying JSON content in the result area. It is as if you download a file from a website. That is just the way how Firefox treats JSON content. You can install JSONView extensions to avoid this behavior.

Feedback

Any suggestion? Please feel free to submit an issue here.