Teaching ASP.NET Web API to WADL

** UPDATE 2 - This was a fun experiment, but if you want to do this sort of thing then check out Swashbuckle . It's an awesome project that gives you Swagger and loads of options!

Introduction

One of the criticisms often cited for HTTP-based services (including REST services) is the lack of documentation/metadata. This is something that ideas such as WADL and Swagger are looking to address.

Recently I’ve been working with Azure API Management which was announced at TechEd recently. Adding the endpoints for your API is one of the first steps that you need to do with API Management, and if you have a large API this can take a while. To help me with this I wanted a quick, lightweight WADL endpoint that integrated with the in-built Web API help pages to add a WADL endpoint. In this post I’ll walk you through the steps to get a basic WADL endpoint wired up.

NOTE: this isn’t a feature complete WADL endpoint (see the list at the end of the post for more details), but it worked for my needs! If it doesn’t do everything that you need then it will hopefully provide a starting point that you can customise to add the extra functionality.

Getting Started

If you have an existing ASP.NET Web API project (or are familiar with Web API) then feel free to skip to the next section. For this post I’m using Visual Studio 2013 and ASP.NET Web API 2.

Create a new Web Application project and choose the Web API template:

This will create a sample Web API controller:

As indicated by the comments, if you run the project and navigate to /api/values you will see the following output:

Navigating to /api/values/1 will instead show:

Having comments that tell you what the URLs are is all well and good, but it isn’t discoverable for consumers! To help with this, Web API exposes Help Pages. If you navigate to /help you will see the auto-generated documentation pages:

Clicking on the links allows you to drill into the documentation for individual endpoints:

Whilst the help pages are very useful, they are intended for human consumption. Wouldn’t it be nice if it exposed the information in a format that was machine-consumable? The rest of this post will take a look at how we can start to add this functionality

WADL 101

In a nutshell, WADL is an xml format for describing HTTP-based services. If (like me) WADL isn’t something that you’ve worked with before then you may want to take a look at some of the following links:

Now we can add the view for the Wadl action. Adding a view might not seem particularly intuitive here, but we’re generating xml output, and Razor works well with angle brackets! The full source for the Wadl.cshtml view is here – you will need to change the namespaces to match your project (unless you called it WebApiWadl like me!).

Build and run the project again, and this time navigate to /help/wadl and you should see a page of xml describing your api!

Importing into Azure API Management

The next step is to create the API in API Management. If you are new to Azure API Management then take a look at the Getting Started guide.

From within the management console (linked to on the dashboard for the API Management instance in the Azure portal), select Import API:

This gives the option to choose WADL or Swagger (clearly we’ll pick WADL at this point). You can then choose to paste in the WADL, upload it as a file, or enter the URL to the WADL (if it is publically accessible).

Once you’ve done this then API Management will import your API as shown below.

Adding form url encoded samples

If you look through the help pages you may notice that the samples for form url encoded requests are missing. This is a limitation of the formatter that is used to handle form url encoded data - it only has support for parsing the format, not generating it. As a quick workaround you can add entries to the HelpPageConfig (under Areas\HelpPage\App_Start):