Introducing WebApiProxy: Providing JavaScript & C# proxies with Intellisense including documentation for ASP.NET Web API

Fanie Reynders

• 3 min read

WebApiProxy extends your ASP.NET Web API service with a proxy endpoint, providing a ready-to-use JavaScript client as well as metadata, exposing the types used in the service. If you are using the documentation provider from ASP.NET Web API Help Pages, the usage documentation is also included inside the metadata, giving the client-side developer a rich experience with Intellisense.

This release has been updated and includes much more great features. Read more on the update here.

A while ago, I wrote about the concept of using T4 templates, to generate C# client proxies for RESTful Web APIs in ASP.NET; and received good feedback. I’ve received plenty of e-mails requesting more information on the official release date. At that time, there were already some super cool implementations around, like ProxyApi, that provides a JavaScript proxy for ASP.NET Web APIs, but no C# proxy (yet).

The idea of JavaScript proxy generation is inspired by SignalR whereby the code is scanned for controllers and methods. Based on the type information, it compiles a JavaScript proxy that can be referenced from HTML. This got me thinking – why not expose the metadata as well? By doing this, it gives us the opportunity to create a client side generator, like a build task, to generate a proxy based on the metadata for communicating to a ASP.NET Web API service, in any language – like C#.

Currently, we have the following technologies:

I’ve noticed that ASP.NET Web API 2 comes stock standard with an ApiExplorer that retrieves the type information of the service, so I built a proxy provider that installs a message handler, using the ApiExplorer to return the service metadata as the response. Also, if the documentation provider (from ASP.NET Web API 2 Help Pages) is used in your service, the documentation will also appear in the metadata response.

The WebApiProxy Provider

This extension provides a proxy endpoint in your service as /api/proxies that serves a JavaScript client and service metadata. All you need to do is install it from NuGet:

Install-Package WebApiProxy
Note: This package requires the core libraries of ASP.NET Web API (version 5 or higher)

Given a Person API on the server:

public class PersonController : ApiController  
{
    public Person Get(int id) {
    return new Person { Name = "Steve" }
    }
}

Allows you to use it in JavaScript like this:

$.proxies.person.get(2)
  .done(function(person) {
    //use person
  });

Simply reference the proxy endpoint provided inside your HTML and you're good to go:

<script src="api/proxies"></script>
This functionality was adopted from ProxyApi - kudos to Stephen Greatrex :)

Invoke the service on its proxy endpoint with the request header X-PROXY-TYPE as "metadata" and the service metadata (including documentation*) will be in the response.

The WebApi C# Proxy Generator

The WebApi C# Proxy Generator is a build task to seamlessly generate a client-side C# Proxy upon project build, for communicating to a ASP.NET Web API service that implements the WebApi Proxy Provider on the server.

Install-Package WebApiProxy.CSharp
This package requires the libraries of ASP.NET Web API Client (version 5 or higher)

The C# proxy code will be generated every time you re-build the project and is based on specific configuration in the WebApiProxy.config file:

The generated code is cached to avoid compilation errors if the service isn't reachable at that time

Now, given a PeopleController on the service-side: It can be used like this on a client like a Console Application or Windows Phone app:

If the types are not found (or resolved) after build, simply give your project a restart or restart Visual Studio.

It even has nice Intellisense including documentation provided by the documentation provider:

The documentation on the Intellisense will only appear if the service uses the documentation provider. You can use the ASP.NET Web API Help Page package on NuGet

You can follow the project on Github here

Till next time!