How About IoC?

The code examples can be found here. Do what you will with it, but as always, no warranty for you!

Sweet sweet abstraction. Its a pretty powerful thing, right? From a clients perspective everything is nice and tidy, while all of the nasty not so pretty details are tucked away under the covers. And as we all know, in statically typed languages, the king of abstraction is the mighty mighty interface. But it might surprise you, that with the ASP.Net Web API,  you cannot use interfaces as parameters to your action methods (say what!!!!!). To be fair, if you think about it, it actually does make sense. After all, how can model binders and formatters possibly know what concrete type you want when they encounter an IFoo interface at run-time. In fact, if you try it, the formatters wont even try, resulting in a lovely null reference exception somewhere down the stack. So if you wanted to do something similar to the code snip below, you are out of luck my friend.

using System.Web.Http;
using WebApiInterface.Models;

namespace WebApiInterface.Controllers
{
    public class FooController : ApiController
    {
        public void Post(IFoo foo)
        {
            //Do some stuff to foo
        }
    }
}

So why doesn’t this work? Again, because the JSON formatter cannot determine the desired run-time type of IFoo you want, it simply skips it. And as a result, you will be left with null. Like I said, its very sad, but it makes sense.

So, what can we do to support this? 

At first glance it may seem like simply plugging in some good ol’ inversion of control might be the answer. After all IoC fixes everything, right? For those of you not familiar with some of the extension points of the Web API, let me explain how leveraging IoC might help. In the Web API’s Global Configuration there is a DependencyResolver property exposed.

GlobalConfiguration.Configuration.DependencyResolver

By setting this configuration option to an IoC enabled dependency resolver, we can control how the Web API resolves dependencies. So for example, when the Web API creates our controllers and it comes across an interface parameter, we can tell it to look in our IoC container for the run-time type bound to the specified interface. This is very useful for injecting a UnitOfWork a Service or any other object we need in our controller. While this is a great first step, it does not directly help us with our desire to have interface types as action parameters.  But it is a very important first step, so lets take a look at how we plug IoC into the ASP.Net Web API

Setting Up IoC

OK, let me first say that I know most of the cool kids hate on Unity. But hey, I don’t wear skinny jeans, I still have a PC, and I have grown used to the judgmental glares I get at my local coffee shop as I proudly play with my windows phone. That said, for simple no frills IoC support I still think its a really nice option. So with some help from the great NuGet package we are going to set up our Web API to use unity as our dependency resolver. First run the NuGet package, here are some details on the set up. Once Unity is set up, we need to configure our container like so.

namespace WebApiInterface
{
    public static class UnityConfig
    {
        public static void RegisterComponents()
        {
	    var container = new UnityContainer();
            container.RegisterType<IFoo, Foo>();
            GlobalConfiguration.Configuration.DependencyResolver = new UnityDependencyResolver(container);
        }
    }
}

Nothing too fancy, just a simple registration stating that when a controller constructor asks for an IFoo, it should get an instance of  type Foo.  Additionally, you can see  that I am setting the DependencyResolver configuration option I mentioned above to the a new instance of the UnityDependencyResolver supplied by the Untiy.WebApi Nuget package. This is what does the actual work of resolving the object instances from the container. With these changes our IoC configuration is ready to go. And god willing, when our controllers are created any dependencies they declare will be resolved by way of our unity container.

We have a Foo Instance!

And there it is.

But What About Our Action Methods

While setting up IoC this way works great to resolve interface types when our constructors ask for them.  It does nothing to help us in our action methods. The image below shows an http post to our Foo controller. As you can see we end up with a null, not a Foo.

No Foo 😦

 

 

Custom Creation Converter

OK so how can we leverage our IoC container setup to resolve interface types in our action methods. As it turns out, for that we need to look for extension points within our configured formatter for a solution.  While the Web API’s Dependency Resolver will help us with constructor injection, it does nothing to help us with our action methods. For that we need something a a little different.

For those of you who want a wonderful explanation of model binding and formatters: read this, its a great article.

Looking at our problem it turns out that  JSON.Net has one very slick extension option that can help us.  And that is the Custom Creation Converter. Much like our dependency resolver gives the Web API the ability to do constructor injection, Custom Creation Converters give JSON.Net specific instructions on how to create object instances during the deserialization process. So when JSON.Net is walking down our object graph, as it finds interface types, it will look for a configured Custom Creation Converter to delegate the object creation process to. This allows us to explicitly influence how objects are created when specific interfaces are found during the model binding process.

The Custom Converter

Here is the code for our custom creation converter.

 public class FooCustomConverter : CustomCreationConverter<IFoo>
    {
        public override IFoo Create(Type objectType)
        {
            return new Foo();
        }

        public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
        {
            if (reader.TokenType == JsonToken.Null)
            {
                return null;
            }

            IFoo obj = Create(objectType);
            serializer.Populate(reader, obj);
            return obj;
        }
    }

And in order to tell JSON.Net to use this converter we also need to register it. Again we can use the global configuration objects for this.

GlobalConfiguration.Configuration.Formatters.JsonFormatter.SerializerSettings.Converters.Add(new FooCustomConverter());

As you can see there is not much to this at all. First we simply derive from the CustomCreationConverter<T> given to us by the JSON.Net framework. This gives us two methods we need to override. First, the Create method. This method creates a new instance of our Foo object. Second, the ReadJson method. This method is called for us by JSON.Net as it reads each JSON element. There are a few things to note here. We want to return null when the token type is null. This happens when no value is supplied for the JSON element. If the token type is not null, we call the Create method to create the new Foo object. Then we use the supplied serializer instance to map the JSON bits into the new Foo object by calling the populate method. And last we return the newly created and mapped object so JSON.Net can add it to the object graph that is being created.

All and all this is pretty simple, but this design has some very serious flaws. For one, it would required a CustomCreationConverter for every interface type you want to support, boo. Secondly since our converters are not using IoC, if we want to support multiple derived types, that logic needs to be put into the converters somehow, booooooooooo.  So, lets tighten up our implementation so both of those problems go away.

Enter The IoC Custom Creation Converter

Since we have IoC all ready wired up, it is possible to create a single CustomerCreationConverter to service all of our needs. Notice in the code below, that in our override of the ReadJson method  JSON.Net is kind enough to supply us with the type information for each object it is trying to deserialize. This information is precisely what we need to delegate object creation to our unity container. Lets take a look at what this might look like.

public class IocCustomCreationConverter<T> : CustomCreationConverter<T>
    {
        public IocCustomCreationConverter() { }

        public override T Create(Type objectType)
        {
            return (T)ServiceLocator.Current.GetInstance(objectType);
        }

        public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
        {
            if (reader.TokenType == JsonToken.Null)
            {
                return null;
            }

            var obj = Create(objectType, reader, serializer);
            serializer.Populate(reader, obj);
            return obj;
        }
    }

As you can see, we did not have to change the code very much. In fact the only major change is in the Create method. Here we ask the container (via the service locator) to create the object instance for us, as opposed to us manually ‘newing’ up the object. We are using the ServiceLocator pattern so we do not need direct access to the container in our JSON serilaizer.  If you are not familiar with the ServiceLocator pattern, here is a quick primer on it. Now that we have our IoCCustomerCreationConverter ready to go we need to register this with JSON.Net with the simple one-liner below.

GlobalConfiguration.Configuration.Formatters.JsonFormatter.SerializerSettings.Converters.Add(new IocCustomCreationConverter<IActionParameter>());

One thing you might notice here is that I am registering the custom creation converter to only work with types that derive from IActionParameter. This is not required but there are some things that we may not want to use our Custom Creation Convert for. For primitive types such as an int or bool, it does not make any sense to ask JSON.Net to use a custom converter. So by using this simple marker interface we can control what types are actually resolved using our new converter.

Wrapping Up

So there you have it! By configuring IoC and adding a single JSON.Net Custom Creation Converter, we are now able to abstract the parameters to our action methods. This is great for testability, as well as creating APIs that may need to serve multiple clients with varying data structures. And that is a pretty cool thing!

BDN

 

 

Web API and Interface Parameters

Securing The ASP.NET Web API

A question I get over and over again when presenting on the ASP.NET Web API is, “How does Authentication and Authorization work in the Web API?” This seemingly simple question is actually one of the most complex aspects of the Web API; largely because the framework ignores any formal support for it. Sure, we have the AuthorizeAttribute, but as we’ll see, this has many limitations that prevent it from being a viable option. We can rely on a hosting environment such as IIS, but this also has its limitations. At the end of the day, to address security, we as service developers need to get our hands dirty and do some actual work. The trouble is that, with a plethora of approaches out there, navigating the topic gets overwhelming very quickly. As such, my modus operandi for this blog series is to present and demystify some of the common options available. I will not cover all of them (that would take a book or twelve), but I will cover the most common solutions to the problem. The intention is to give the .NET community what I wished I had when I started working with the ASP.NET Web API.

So for all of the folks out there who have asked me about the Web API’s security model and been given sub-par explanations, I hope this blog series can help clear up some of the confusion for all of us!

What the Series Will Cover

From a bird’s eye view, the list below outlines the concepts this series will cover. The truth is, one could write a blog series on these concepts individually;  but, I will attempt to distill the information in a way that is practical and still covers the essential aspects of each topic.

1. AuthorizeAttribute
2. Basic Authentication
3. Digest Authentication
4. Security Token Services
5. OAuth and OpenID

Security Primer

When looking at the topic of application security, there are many factors involved. Depending on your situation, your idea of secure may be different from someone else’s. For example, the security demands on a banking system will likely be much more stringent than that on a reservation system for a hair salon. That being said, I do want to review the core concepts involved in system security. If you find yourself hungry for more; a much more in-depth summary can be found here.

1. Confidentiality – Ensuring that only those intended to have access to your data can gain access to it.
2. Integrity – Ensuring accuracy of your data
3. Authenticity – Ensure that both parties involved in a transaction are who they say they are

There are several other concepts involved such as Non-repudiation and Availability. However, I am going to focus on what I consider the core concepts and what is most often needed when building a system.

Part 1 – Moving Towards Basic Authentication

The code examples can be found here. Do what you will with it, but as always, no warranty for you!

The ASP.NET Web API does very little address to the security story. For better or worse it is not addressed. Much of the documentation and examples out there show the usage of the AuthorizeAttribute, or the heavy reliance on IIS to manage Authentication and Authorization. In Part 1 of this series, we will explore why the AuthorizeAttribute falls short, and how we can make some minor enhancements to our API to move to the HTTP Basic Authentication Standard. So, with introductions out of the way, let’s get started!

Your Friend/Foe – the AuthorizeAttribute

Oh… if only the security story was as easy as adding an attribute to your controller actions, what a great world it would be. It would also be nice if we did not need to worry about security. Unfortunately, both of these niceties are a pipe dream. For now let’s play the devil’s advocate and take a quick look at how the AuthorizeAttribute works. Then we can talk about why you should never use with a production grade service.

Using the AuthorizeAttribute is very simple. As with its MVC counterpart all you need to do is decorate your action method or controller class with it and BAAAM! Now you have security. Let’s look at a quick example.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace WebAPIAuth.Controllers
{
    public class TestController : ApiController
    {
        [Authorize]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }
    }
}

By simply adding this attribute to your action method, any unauthenticated requests to our Web API will reply with a HTTP 401 (unauthorized) response. Take a look at the request below to the TestController.

Pretty slick right? Well, not so fast. Though this is simple enough to implement, there are several serious limitations to doing things this way. The central problem with this approach is the underlying mechanism it uses to do its work. Both the ASP.NET Web API’s AuthorizeAttribute and its MVC counterpart rely on  Forms Based Authentication to authenticate incoming requests. In Forms Based Authentication, cookies are used to transport the authentication ticket between client and server. Not only does the use of cookies add state to our services that should be stateless, they also limit the potential set of clients to only those that understand how to work with them. This limitation is unacceptable in today’s landscape with such a disparate set of potential clients. From an architectural stand point, there are additional concerns to consider. Chief among them that the AuthorizeAttribute deals only with Authorization. For Authentication, it relies on the ASP.NET Pipelines FormsAuthenticationModule. Therefore, unless you are using it in conjunction with an ASP.NET application you really cannot rely on this approach at all. From a security standpoint let’s look at how this approach holds up to our security concepts.

Does it support Confidentiality?

No. Any servers between a request and your Web API would be able to see the content of the request and response.

Does it support integrity?  

No. It does nothing to ensure that data has not been tampered with by the time a request reaches your Web API.

Does it support Authenticity?

At some level this is supported. The authentication ticket is passed from client to the server via cookies. However, these kinds of ad-hoc implementations are inherently susceptible to phishing and unless some sort of transport security is used in conjunction with cookies, credentials are sent across the wire in clear text.

To sum it up, because the AuthorizeAttribute relies on Forms Based Authentication, we cannot and should not ever use it to secure our Web API.

Basic Authentication

So now that we know using Forms Based Authentication is a non-starter, the next thing we can consider is Basic Authentication. Basic Authentication is a very attractive option since it is part of the HTTP standard. Moreover, as the name states it is a very simple form of authentication. Let’s quickly outline the steps involved in Basic Authentication.

1. Client makes a HTTP Request to a protected resource
2. Server responds with the HTTP 401 (unauthorized) status code. The response should also contain the ‘WWW-Authenticate’ header
3. The presence of the ‘WWW-Authenticate’ header indicates to the client that authentication is required
4. Client makes the same request passing along the credentials in the ‘authorization’ header
5. Server authenticates the user using the supplied credentials
6. Server authorizes that the user has access to the request resource
7. If the user is authorized the resource is returned to the client, if not an HTTP 401 (unauthorized) is returned

Here is a simple sequence diagram outlining Basic Authentication from one of my favorite tools.

This simple approach does not require cookies, session, or any other type of state to be managed by our Web API. However, there are some concerns worth noting here. First, because our Web API is supposed to be stateless, Basic Authentication requires the client to send its credentials with every request. This forces the server to authenticate and authorize each request, potentially introducing some unwanted overhead depending on how your application does these things. Secondly, Basic Authentication does nothing to protect the credentials being sent across the wire.  Looking at the example of the authorization header below; you may be led to believe that there is some sort of encryption going on, I assure you there is not.

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

The value of the Authorization header may look encrypted, but it is actually the name and password encoded in Base64. This means the clients credentials are essentially sent to the server in clear text. For Basic Authentication to be viable at all, we must always use it in conjunction with some form of TLS (think SSL all the time).  Let’s take a look at how we might implement Basic Authentication with the ASP.Net Web API.

Basic Authentication Implementation

The first instinct one may have for an implementation might be to roll your own AuthorizeAttribute. This attribute can then be applied to any actions that you want to protect. But from a  Separations of Concerns (SoC) perspective, Authentication and Authorization are completely different animals. Authentication focuses on identifying the user, Authorization focuses on what the user can do in a given system. Having an action filter responsible for both concepts goes against most core object-oriented principles. Even more troubling is how close to your action method the Authentication and Authorization would happen. If we wait until the request makes its way to an Action Filter before even Authenticating the user, a malicious request could make its way much deeper into our call stack than is comfortable. Think of it this way. Is it better lock only your bedroom door while you are sleeping, allowing burglars to make their way into your house, up the stairs, only to be stopped at your bedroom door? Of course not! A more reasonable approach would be to lock all the doors of your house, so burglars cannot intrude in the first place! Similarly, we should reject all unauthenticated requests as soon as possible, limiting the potential damage a malicious request could cause. This is where the Web API’s Message Handlers come in handy. Message Handlers are executed very early in the life cycle of the request/response pair. Message Handlers receive requests when they come in as well as the responses before they are sent back. This allows Message Handlers to inspect and reject a request before it makes its way to our controllers. Message handlers are chained together, much like a linked list, where one handler passes the request to the next. Once the last handler is executed the response is processed much the same way but in reverse. The image below illustrates the ‘pipeline’ style architecture of Message Handlers.

By creating a custom message handler to manage Authentication we can inspect the request as well as alter the response, but better yet, we can do it at a very early stage of the request/response life-cycle.  Let’s take a look at how we might implement this.

The Message Handler

using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading;
using System.Threading.Tasks;
using System.Web;

namespace WebAPIAuth
{
    public class AuthenticationMessageHandler : DelegatingHandler
    {
 protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request
 , System.Threading.CancellationToken cancellationToken)
        {
            if (request.Headers.Authorization != null
                && request.Headers.Authorization.Scheme.Equals("basic", StringComparison.OrdinalIgnoreCase))
            {
                var credentials = request.Headers.Authorization.Parameter.Split(':');

                //Look up user
                var user = new UnitOfWork().Users.GetByCredentials(credentials[0], credentials[1]);
                if (user != null)
                {
                    HttpContext.Current.User = user.ToClaimsPrincipal();
                    Thread.CurrentPrincipal = HttpContext.Current.User;
                }
            }

            var httpResponse = await base.SendAsync(request, cancellationToken);
            if (httpResponse.StatusCode.Equals(HttpStatusCode.Unauthorized))
            {
                httpResponse.Headers.WwwAuthenticate.Add(new AuthenticationHeaderValue("basic"));
            }

 return httpResponse;
        }
    }
}

This simple message handler does everything needed to support Basic Authentication.

1. It checks the request for the presence of the Authorization header.
2. If found it parses the header and extracts the username and password.
3. It then looks up the User based on those credentials, converts the User to a Claims Principal and finally assign it to HttpContext.Current.User and the Thread.CurrentPrincipal.
4. From there it passes execution to the next handler.
5. Once the response comes back it checks the response HttpStatusCode for a 401 (unauthorized) status. If the response is a 401 we add the ‘WWWAuthenticate’ header to indicate to the client that they need to supply their credentials.

One last thing worth mentioning is the use of the ToClaimsPrincipal extension method. This extension method converts our User object into a ClaimsPrincipal object.  Click here for more information about Claims Based Authentication. The code for this is very straight forward. The only thing we are doing here is creating a ClaimsPrincipal object and adding a few claims to its claims collection.

using System.Collections.Generic;
using System.Globalization;
using System.Security.Claims;
using System.Security.Principal;
using WebAPIAuth.Models;

namespace WebAPIAuth
{
    public static class UserExtensions
    {
 public static IPrincipal ToClaimsPrincipal(this User user)
        {
            var claims = new List<Claim>
                {
                    new Claim("UserName", user.UserName),
                    new Claim("UserId", user.Id.ToString(CultureInfo.InvariantCulture)),
                    new Claim(ClaimTypes.Role, user.Role),
                };

            var claimsIdentity = new ClaimsIdentity(claims, "Basic", "UserName", ClaimTypes.Role);
 return new ClaimsPrincipal(claimsIdentity);
        }
    }
}

Now that our message handler is ready, we need to make sure it is executed for each request. To do this, you need to add the following configuration to your WebApiConfig.cs.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace WebAPIAuth
{
    public static class WebApiConfig
    {
 public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );

            config.MessageHandlers.Add(new AuthenticationMessageHandler());
        }
    }
}

With the message handler intact, it will now handle Authentication for us. However, that is not the entire story; we still have the matter of Authorization. Thankfully for that problem we can still rely on the AuthorizeAttribute as it is. When a request reaches our action method, the AuthorizeAttribute will look for an authenticated principal on the current thread. If the principal is present and authenticated, the next step is user authorization. If the current principal is authorized to access the requested action, the action will be executed, and the result return to the client. On the other hand, if there is no authenticated user present, or the user does not have access to the requested action a HTTP Status 401 (unauthorized) will be returned.

In Action

With all of the moving parts ready to go, let’s take a look at this approach in action.

The First Request

The first thing we will do is make a HTTP Request for a protected resource. We will not include our credentials in the authorization header to get a HTTP Response with a status code of 401 (unauthorized).

Looking at the highlighted lines above you can see the request to the protected resource and the 401 (unauthorized) response that was returned. You also can see that the ‘WWW-Authenticate’ header was included. This tells the client that credentials are required.

The Second Request

When clients receive a 401 (unauthorized) response, they can send an additional request, one that contains the authorization header and the credentials of the user making the request. Let’s look at an example of this.

With the presence of the Authorization header complete with the user’s credentials, the user can be authenticated, and all is well with the world.

Wrapping Up

In part one of this series, we looked at a few different things. We looked at the limitations of the AuthorizeAttribute and its reliance on Forms Based Authentication. We looked at how we can support Basic Authentication in our Web API’s. Although Basic Authentication is a very attractive solution because it is both simple, and part of the HTTP standard, it does have some limitations. First and foremost because it offers no type of transport layer security using it without SSL is a not an option. If you are going to use basic authentication, make sure you do it in concert with SSL. Another area of concern is that the credentials are sent to the server with each request, which creates a potential for additional processing overhead. Finally, if your browser caches these credentials, there is some risk of Cross Site Forgery attacks. Even with these limitations, Basic Authentication is the first step to a much more secure Web API. We will take this implementation much further in Part 2 of this series, where we will take a look at Digest Authentication. Digest Authentication is very similar to Basic Authentication, but it is substantially more secure. The additional security precautions of Digest Authentication address most of the concerns that arise from Basic Authentication.

Until next time keep your services safe!

BDN

The Tale of the ASP.NET Web API

As most of you probably know, with the drop of the of the MVC 4 Framework Microsoft introduced us to a shiny new framework called the ASP.NET Web API. Anytime new frameworks come out open source or otherwise, you have to ask yourself a few important questions.

What?

The first and most obvious question we need to ask is “What the heck is this new framework?”.  In the case of the ASP.NET Web API this is a pretty simple question to answer. The ASP.NET Web API is now the recommended approach for developing HTTP based services and REST based services in the .NET stack. See it’s simple!

Why?

Secondly, and more importantly, is the question “Why did the create this framework?”. After all, we have WCF; we have MVC; so why introduce another framework into an area that is already a bit confusing?

An Illustration of Pain

To help illustrate why this framework was introduced, I would like you to look at a few images. While looking at them ask yourself a question. Why are these people feeling so much pain? What is it that is making them look miserable?

Our Distressed Woman

Frustration

Anger

 

So what is going on here? What is it that’s making these folks so angry? As I look at these pictures, this is the story that plays out in my mind.

The Story

This is a group of .NET developers, who for the last three years have been working on a suite of REST based services, but because of the corporate standards of the company they work for they have been forced to do this using WCF. So for the greater part of three to four years, these people have been fighting against a technology that was not necessarily designed to solve the problems they were facing.

HTTP + WCF = 😦

Now I don’t mean any disrespect to WCF. But the truth is that from its inception and from the ground up, WCF was designed with SOAP based web services in mind. It was developed to be highly scalable, highly pluggable, highly configurable as well as any other ‘able’ you can think of. It was also designed to work across multiple transport protocols be it TCP/IP, Named Pipes and most recently even HTTP. All this is extremely powerful stuff  if it is what you want. However,  if what you need is a simple HTTP service to send data to, or to obtain data from, the WCF development experience starts to feel heavy, its hard, its complicated and honestly just not much fun. Thankfully, Microsoft acknowledged this, and as HTTP services became more prevalent they took steps to make things easier on us.

The WebHttpBinding

Enter .NET 3.5 and the introduction of the WebHttpBinding. For the first time,  WCF developers could now expose their WCF services as HTTP end points. A step in the right direction? Absolutely.  However, it did not quite go far enough. Relegating HTTP to more of a transport protocol as apposed to application protocol the WebHttpBinding was more a way to transfer data from one server to another then it was anything else. But the HTTP semantic is much richer than just a transport protocol.  We have things like caching, etags, and many other things that have become more and more important as HTTP services have taken over the service landscape. And its these things that HTTP service developers need to be able to target when building their services. So was the WebHttpBinding  a step in the right direction? Yes. But unfortunately for us it did not go far enough.

The Rest Starter Kit

Next we got something called the Rest Starter Kit. I never actually got to work with this;  however, I have read that it was actually well received by many. However as it is with many things from Microsoft the Rest Starter Kit never made it past the community preview, and as such is just a blip in the .NET history book.

The WCF Web API

The WCF Web API, the third and final attempt to build on top of WCF strong support for HTTP based services. In all fairness to the WCF team,  this was a giant leap in the right direction. We started to see a convention a based approach opposed to the massive WCF configuration files. We were given a nice client to interact with our services, and we even started to see the support for content negotiation. However, this all fell into a category of a too little and too late. .NET developers frustrated with the lack of support for HTTP based services and with open source solutions available, things like OpenRasta, and Service Stack, .NET developers had moved on. Some of the savvier .NET folks even started to build their HTTP services on top of MVC, and even this approach proved to be more straight forward than using the latest WCF Web API.

What To Do

At this point,  Microsoft found themselves in a bit of a precarious position, and they had to make a choice. Do they continue to push WCF into a box it was never intended to fit into or do they stop, look around at the community, and create something directly targeted at the problem of HTTP based services and REST based services. Thankfully for us they chose the latter. And with the release of Visual Studio 2012 and MVC 4 we were given the brand new shiny ASP.NET Web API.

Taking the good from the WCF Web API, and what they have learned form the MVC stack. They created a new framework that brings a slew of desirable features.

Modern

A much more modern HTTP programming model. Largely convention based, Asynchronous from top to bottom, we have a really nice HttpClient to interact with our services, and quite frankly it just a lot of fun to work with.

MVC

Because the ASP.NET Web API is based on top of the MVC framework we get a lot of the magic that exists in the MVC stack. Things like routing, action filters, model validation and of course the added benefit of the development experience feeling very much at home if you are already a MVC developer.

Content Negotiation

As service developers,  we need to be cognisant of the types of data our clients want to work with. Maybe they want XML maybe they want JSON out of the box the ASP.NET Web API supports both. And of course the extensions points are there if you want to create your custom media type, or use something RSS or ATOM.

OData

If you want to expose your HTTP service to URI based queries, there is OData support for that, and it gets better all the time with the ongoing nightly builds.

Testable

And last but not least the framework is testable. If any of you remember how hard it is to unit test, and integration test WCF services, you will understand why this is such a beautiful thing. Built with testability in mind from top to bottom it is one of the most testable frameworks in all of the .NET stack.

Why HTTP?

The last thing I want to address is a question I was first asked when I presented this topic at MDC last year. Someone in the audience asked ‘Why so much emphasis on HTTP, is there something wrong with SOAP based services?’

The answer to that question is simple. There is nothing wrong with SOAP based services. However, in the gadget landscape of today, many devices know how to work with HTTP natively. Far less understand the different abstractions that sit on top HTTP, such as SOAP. So it should not surprise anyone  that HTTP based services are the new standard.

Does this mean SOAP and WCF are dead? No, not at all. WCF and SOAP just solve different problems. If you need to work with multiple transport protocols, or if you need WS-* style security WCF is still the king. Where the ASP.NET Web API shines, is in the space of HTTP. So in short, each solves a different problem, and each solves does it exceptionally well.

-BDN

ASP.NET WEB API Validation (A One More Better Approach)

Before We Start

This post is based on the nightly builds of the ASP.NET Web API. The Web API team is constantly making improvements to the framework, and publishing them with nightly builds on NuGet. Click here for more information on getting setup with the nightly builds, there is a lot of exciting things in them.

I would also like to extend a giant thank you, to Youssef Moussaoui over at Microsoft for fixing the following defect. Without this fix,  the IValidatableObject support outlined in this post would be much more difficult. So thanks Youssef!

And finally, to get the source code for the sample application ‘ResIt’ outlined in this post, click here. And as always no warranty for you!

Background

If you ask me what the most difficult aspect of Business Application Development is, I will say, quickly and confidently, validation! Add to the mix a distributed architecture like Http, and you have the makings for a real bugger of a problem. With rules on the server, rules on the client, and a pile of plumbing code in between, there is a plenty of opportunity for things to get mucked up. Yet, despite all of this complexity, we still need to  provide the user a reasonable validation experience.

So all together now…Validation is hard!

With the ASP.NET MVC Framework we were given lots of fancy tools to help support the validation story. Of course,  we got all kinds of DataAnnotation support, and with MVC 3 we were given another option with the added support for the IValidatableObject interface.  But what does this have to do with the ASP.NET Web API? Well, as it turns out it has a lot to do with it. Because the ASP.NET Web API is build on top of the MVC framework the Web API can take advantage of many of the features that we all know and love in the MVC stack.  Things like Action Filters, Routing, and of course all of the goodness that is Model Binding.

Model Binding Review

For a detailed description of Model Binding please look here. For now, here are the Cliff Notes. Model Binding is how form, querystring, and any other type of data coming in via the Http Request gets converted into the CLR types defined as the input parameters to our action methods. This magic allows us to work with typed .Net objects in our actions, as opposed to developers having to interrogate the HTTP Request directly. And this is my friend is a marvellous thing! Oh, but there’s more! Not only does Model Binding handle the nasty right to left mapping between the incoming HTTP Request and our .Net types. Model Binding validates our model using Model Validation, and it’s this part of the MVC stack that we are interested in, at least for this post.

Model Validation is the process where the framework takes our objects already created by Model Binding  and inspects their properties for any DataAnnotations. If  found, the Validate method of the each DataAnnotation is executed. This process then invalidates any objects that don’t meet the business rules as defined by the supplied DataAnnotation. So why is this relevant to the Web API? Simply put, because the Web API has complete Model Binding and  Model Validation support, any of the techniques we use for validation in  MVC is fair game. This includes both DataAnnotations and the IValidatableObject interface.

Boo To You Mr. Data Annotation

Generally speaking, I am not a fan of the ever so popular attribution method of validation.  First of all they tend to break down as soon as something difficult arises. Secondly, they are not terribly explicit, and out of sight out of mind, right? Thirdly, and most importantly, I have never been able to figure out how to use the hooks for client validation when creating custom validators (Just can’t find the energy to do it). I will admit that in the context of ASP.NET MVC DataAnnotations do have one tantalizing benefit with the added JavaScript support (sometimes). However, with the ASP.NET Web API that benefit does not actually exist, after all we are not returning markup and JavaScript to the client, we are returning resources formatted in JSON or XML. With the absence of the JavaScript benefit,  I assert that DataAnnotations make validation harder when working with the Web API, and as such, I avoid them as a rule.

One More Better Validation

The technique I am going to outline here is one that I have used  successfully in several projects. It leverages one of my favorite open source frameworks, Fluent Validation, coupled with the WEB API’s  support for the IValidatableObject interface. Using Fluent Validation, we will make individual validators for each our domain objects. These validators are both explicit and testable, both traits that get two thumbs up from me. Combing these validators with the Web API support for the IValidableObject interface, we will create what I consider a pretty slick solution to the validation problem.

How It Works

Before we get into the dirty details, let’s talk  about the sequence events we are going to look at.

1. Using JQuery, we send an invalid HTTP Post Request to our Web API
2. Model Binding does its thing, converting the request into a Reservation object
3. Model Validation honors the IValidatableObject contract, calling the Validate method of our Reservation object
4. The Validate method delegates to our Fluent Validator, invalidating the Reservation object
5. Our WEB API returns an HTTP Response, with a Status Code 400 (bad request) back to the client, along with a list of error messages
6. jQuery unobtrusive will then render these errors to the screen

This image below illustrates the sequence of events using a  super slick tool.

Basic Validation Sequence

Our Sample Application

Before we get into the meat of this example, I want to introduce to you our sample application. Our sample application is a fictional Reservation web site called ‘Resit’. Resit is a simple application, it consists of a single screen, that allows users to add reservations. In addition to the screen, we also have a Web API that will be responsible for the validation of our models and any data access required. Finally, we have a single domain object named Reservation. The Reservaion object  implements the IValidatableObject interface and leverages Fluent Validation to execute any validation rules that may be needed.

The View

Our view is nothing more than a simple Html form with the following fields.

1. First Name
2. Last Name
3. Reservation Date

It looks a little something like this (yeah I know it is not real purty!)

Not a Picasso

Not much going on here, just a simple HTML form taking advantage of the boilerplate MVC look and feel. Oh, and of course, the very ugly HTML 5 control that is rendered for dates automagically. Lets take a look at the code for the view.

@model BetterValidation.Models.Reservation
@{
    ViewBag.Title = "ResIt!";
    Layout = "~/Views/Shared/_Layout.cshtml";
}
<header>
    <div class="content-wrapper">
        <div class="float-left">
            <p class="site-title">
                <a href="~/">ResIt</a>
            </p>
        </div>
    </div>
</header>
<div id="body">
    <section class="featured">
        <div class="content-wrapper">
            <hgroup class="title">
                <h1>Welcome To ResIt!</h1>
                <h2>A generally useless reservation system</h2>
            </hgroup>
            <p>
                ResIt allows you to create a reservation. Your reservation will not be saved to any kind of database. You will not be
                able to edit your reservation. But you will be able to see validation messages. 🙂
            </p>
            <p>
                To learn more about FluentValidation Visit
                <a href="http://fluentvalidation.codeplex.com/" title="FluentValidation">FluentValidation</a>.
                <br />
                <br />
                To learn more about Me Visit <a href="http://www.brette.net" title="Brette.Net">Brette.Net Consulting</a>.
            </p>
        </div>
    </section>
    <section class="content-wrapper main-content clear-fix">
        <h2>Create A New Reservation</h2>
 <form id="createReservationForm">
            <fieldset>
                <legend>Reservation</legend>

                <div class="editor-label">
                    <label class="required" for="FirstName">
                        First Name</label>
                </div>
                <div class="editor-field">
                    <input class="text-box single-line" id="FirstName" name="FirstName" type="text" />
                    <span class="field-validation-valid" data-valmsg-for="FirstName" data-valmsg-replace="true" />
                </div>
                <div class="editor-label">
                    <label class="required" for="LastName">
                        Last Name</label>
                </div>
                <div class="editor-field">
                    <input class="text-box single-line" id="LastName" name="LastName" type="text" />
                    <span class="field-validation-valid" data-valmsg-for="LastName" data-valmsg-replace="true" />
                </div>
                <div class="editor-label">
                    <label class="required" for="Date">
                        Date</label>
                </div>
                <div class="editor-field">
                    <input class="text-box single-line" id="Date" name="Date" type="date" />
                    <span class="field-validation-valid" data-valmsg-for="Date" data-valmsg-replace="true" />
                </div>

 <input type="button" id="cancelButton" value="Cancel" />
 <input type="submit" id="saveButton" value="Save" />
            </fieldset>
        </form>
    </section>
</div>
@section scripts{
    <script type="text/javascript">
 $('#createReservationForm').submit(function (submitEvent) {
            submitEvent.preventDefault();
            var form = $('#createReservationForm');
            $.validator.unobtrusive.parse(form);
            if (form.valid()) {
                $.ajax({
 url: "api/Reservation/Create",
                    data: $("form").serialize(),
                    type: "POST",
 statusCode: {
                        200: function () {
 clearErrors($('#createReservationForm'));
                            alert("You created a reservation");
                        },
                        400: function (response) {
 var validationErrors = $.parseJSON(response.responseText);
 $.each(validationErrors.ModelState, function (i, ival) {
 remoteErrors(form, i, ival);
                            });
                        }
                    }
                });
            }
        });
    </script>
}

The Form

The first thing you will notice is the presence of our Html form. A simple little form that contains the inputs for the First Name, Last Name, and Date. Additionally we also have included the data-attributes  required to support jQuery validation. Finally, you will see the empty span element that will eventually render our error messages sent back from our Web API.

The JavaScript

Of course,  no html form is complete without a bunch of messy JavaScript at the bottom of the screen, and this form is no exception! Looking at the JavaScript, we are really only doing a few things. First, when the form is submitted I use JQuery to make an Ajax HTTP Post Request to our Web API. With it, I send along the serialized form data. If the HTTP Response comes back with a HTTP Status Code 200 (OK), I pop up a very visually pleasing alert dialog, indicating that the reservation has been created. If, however, the HTTP Response from the server  has a HTTP Status Code 400 (Bad Request), I do a few additional things. First, I parse the responseText converting the returned JSON into a living and breathing JavaScript object. I then iterate over the errors in the Model State calling the remoteErrors method (more on this later). For now just know that the remoteErrors function is responsible for rendering the error messages to the screen.

Reservation Object

Next lets talk briefly about our Reservation object. This is not very exciting containing only a few properties (FirstName, LastName, Date) however one important thing to notice is that it implements the IValidatableObject interface. And if you remember our conversation about Model Binding you will know that both the the MVC framework and the Web API honor this contract when running through the Model Validation process.

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using BetterValidation.Extensions;
using FluentValidation;
using ValidationContext = System.ComponentModel.DataAnnotations.ValidationContext;

namespace BetterValidation.Models
{
    ///
    /// Simple Domain Object
    ///
    public class Reservation : IValidatableObject
    {
        #region Private Members

        private readonly IValidator _validator;

        #endregion

        #region Properties

        ///
        /// Gets or sets the date time.
        ///
        ///
        /// The date time.
        ///
        public DateTime DateTime { get; set; }
        ///
        /// Gets or sets the name.
        ///
        ///
        /// The name.
        ///
        public string FirstName { get; set; }
        ///
        /// Gets or sets the name.
        ///
        ///
        /// The name.
        ///
        public string LastName { get; set; }

        #endregion

        #region Constructor

        ///
        /// Initializes a new instance of the  class.
        ///
        public Reservation()
        {
            _validator = new ReservationValidator();
        }

        #endregion

        #region IValidatableObject

        ///
        /// Determines whether the specified object is valid.
        ///
        ///The validation context.
        ///
        /// A collection that holds failed-validation information.
        ///
        ///
        public IEnumerable Validate(ValidationContext validationContext)
        {
            return _validator.Validate(this).ToValidationResult();
        }

        #endregion
    }
}

IValidatableObject gives us a single method aptly name Validate. This method takes in a ValidationContext object, and as you can see simply delegates to our ReservationValidator (a Fluent Validator) object. During Model Validation,  the Web API will call this method on any object that implements this interface giving us a chance to run any validation rules for each object as its Model Bound.

Reservation Validator

This class represents all of the business rules for our Reservation object. Notice that it derives from the AbstractValidator<T> class. This class is one of the base classes available to us from the Fluent Validation framework. The only other interesting thing here is the rule definitions in the constructor of our validator. Notice I create two rules, the first, requires the FirstName property to be valued, and the second, requires the LastName to be valued.

using FluentValidation;

namespace BetterValidation.Models
{
    public class ReservationValidator : AbstractValidator
    {
        ///
        /// Initializes a new instance of the  class.
        ///
        public ReservationValidator()
        {
            RuleFor(item => item.FirstName)
                .NotEmpty();

            RuleFor(item => item.LastName)
              .NotEmpty();
        }
    }
}

The last thing I want to point out here, is a simple extension method I have added to the FluentValidation.Results.ValidationResult type. This extension method simply converts the FluentValidation ValidationResult type to the  System.ComponentModel.DataAnnotations.ValidationResult type that both the MVC and the Web API expect. It’s only a few lines of code, but this is required since the types are actually different.

using System.Collections.Generic;
using System.Linq;
using ValidationResult = System.ComponentModel.DataAnnotations.ValidationResult;

namespace BetterValidation.Extensions
{
    /// <summary>
    /// Extension to the Fluent Validation Types
    /// </summary>
    public static class FluentValidationExtensions
    {
        /// <summary>
        /// Converts the Fluent Validation result to the type the both mvc and ef expect
        /// </summary>
        /// <param name="validationResult">The validation result.</param>
        /// <returns></returns>
        public static IEnumerable<ValidationResult> ToValidationResult(
            this FluentValidation.Results.ValidationResult validationResult)
        {
            var results = validationResult.Errors.Select(item => new ValidationResult(item.ErrorMessage, new List<string> { item.PropertyName }));
            return results;
        }
    }
}

So Far

Just a quick recap. So far we have a Simple view with a Html form, a Reservation domain object that implements IValidatableObject, a single Validator object called ReservationValidator. Based on what we now know about Model Binding and Model Validation, we know that when our form is posted to our Web API, Model Validation will call the Validated method on our Reservation object. That method creates the instance of the ReservationValidator, and all the validation rules are executed. The results are converted into the System.ComponentModel.DataAnnotations.ValidationResult object that is eventually stuffed into Model State and streamed back to our client.

Our Web API

The last major component of our validation solution is our Web API,  this is, after all what the post is all about right?

using System.Net;
using System.Net.Http;
using System.Web.Http;
using BetterValidation.ActionFilters;
using BetterValidation.Models;

namespace BetterValidation.Controllers
{
    public class ReservationController : ApiController
    {
        [ValidationResponseFilter]
        public HttpResponseMessage Post(Reservation reservation)
        {
            return Request.CreateResponse(HttpStatusCode.OK, reservation);
        }
    }
}

Looking at the ReservationController,  you know this is our Web API because it derives from ApiController. Our Web API boasts a single Post action; this action takes in an instance of our Reservation domain object, created for us by Model Binding of course. Assuming there are no validation errors, this action  simply streams the reservation back to the client with a HTTP Status Code of 200 (OK), and all is well with the world. However, what happens if the incoming HTTP Request is incomplete, or if it’s invalid? How can we communicate this information back to the client? This brings us to the ValidationResponseFilter that decorates our fancy Post action.

Action Filters a Primer

Just a quick refresher on Action Filters. Action Filters are a terrific way to support cross cutting concerns in our applications. As such, they let us execute code just before an action is executed by overriding the OnActionExecuting method. They also let us execute code just after an action executes by overriding the OnActionExecuted method. This gives us a excellent way to add aspect oriented behavior to any action by simply decorating an action method with an attribute. One important thing to note about the OnActionExecuting method  is that it executed after  the Model Binding process. What this means is, that by the time the OnActionExecuting method is executed, both Model Binding and Model Validation have already run. This results in any validation errors being stuffed into Model State just before our action filter is executed. Using this little tidbit of life cycle knowledge we can do something pretty slick. Enter the ValidationResponseFilter!

ValidationResponseFilter

Looking at the action filter below, notice the implementation of the OnActionExecuting method is checking to see if any validation errors were found. After all, Model Binding has already done its magic, so all errors would be present in Model State at this point. If the Model State is invalid, I ask the HttpRequest object to create for us a special kind of HttpResponse using the CreateErrorResponse method. This overload is special because it actually takes in as an input parameter the Model State information containing all of the validation errors. Using the Model State information, CreateErrorResponse creates an HttpResponseMessage that includes a list of validation messages in such a way that JavaScript frameworks like JQuery can consume them. So by simply annotating a method with this attribute, any validation errors found during the Model Validation process are sent back to the client structure in a JavaScript friendly way.

using System.Net;
using System.Net.Http;
using System.Web.Http.Filters;

namespace BetterValidation.ActionFilters
{
    public class ValidationResponseFilter : ActionFilterAttribute
    {
        ///
        /// Called when [action executing].
        ///
        ///The action context.
        public override void OnActionExecuting(System.Web.Http.Controllers.HttpActionContext actionContext)
        {
            if (!actionContext.ModelState.IsValid)
            {
                //actionContext.ModelState.Keys
                actionContext.Response = actionContext
                        .Request
                        .CreateErrorResponse(HttpStatusCode.BadRequest, actionContext.ModelState);
            }
        }
    }
}

Remote Errors

The last thing I need to touch on, is the  JavaScript method remoteErrors. This method is called when our Web API returns a Http Status Code 400 (Bad Request), and it has a few responsibilities. First, it is in charge of inspecting the Model State errors that came back from the server and locating the related input elements. This is done by parsing the dot path information supplied in Model State, and matching it to the data-valmsg-for data attribute of our input controls. Once found, the correct style is applied, and the error message is placed the span element next to the input control. This approach was inspired from a post I found on stack overflow, you can find it here. I have found this to be a pretty straight forward way to deal with the Model State errors that come back from the server. While I am sure there are a million other ways you can do the same thing, I found this to be clean and simple, so I ran with it.

function remoteErrors(jForm, name, errors) {

    function inner_ServerErrors(name, elements) {
        var ToApply = function () {
            for (var i = 0; i < elements.length; i++) {
                var currElement = elements[i];
                var currDom = $('#' + name.split('.')[1]);
                if (currDom.length == 0) continue;
                var currForm = currDom.parents('form').first();
                if (currForm.length == 0) continue;

                if (!currDom.hasClass('input-validation-error'))
                    currDom.addClass('input-validation-error');
                var currDisplay = $(currForm).find("[data-valmsg-for='" + name.split('.')[1] + "']");
                if (currDisplay.length > 0) {
                    currDisplay.removeClass("field-validation-valid").addClass("field-validation-error");
                    if (currDisplay.attr("data-valmsg-replace") !== false) {
                        currDisplay.empty();
                        currDisplay.text(currElement);
                    }
                }
            }
        };
        setTimeout(ToApply, 0);
    }

    jForm.find('.input-validation-error').removeClass('input-validation-error');
    jForm.find('.field-validation-error').removeClass('field-validation-error').addClass('field-validation-valid');
    var container = jForm.find("[data-valmsg-summary=true]");
    list = container.find("ul");
    list.empty();
    if (errors && errors.length > 0) {
        $.each(errors, function (i, ival) {
            $("<li />").html(ival).appendTo(list);
        });
        container.addClass("validation-summary-errors").removeClass("validation-summary-valid");
        inner_ServerErrors(name, errors);
        setTimeout(function () { jForm.find('span.input-validation-error[data-element-type]').removeClass('input-validation-error') }, 0);
    }
    else {
        container.addClass("validation-summary-valid").removeClass("validation-summary-errors");
    }
}

function clearErrors(jForm) {
    remoteErrors(jForm, []);
}

Summary

Validation is hard. In a distributed environment it’s harder. With so many moving parts and so many disparate technologies involved (Html, JavaScript, C#, Http), it can be a challenging thing to do in a testable and maintainable way. While there are many different ways one can approach this problem, the solution I have outlined here has held up to most requirements I have had to deal with when using the ASP.NET Web API. By avoiding DataAnnotations, and plugging into the support IValidatableObject interface, we can create clear, testable Validator objects, and still take full advantage of the Model Binding support of the framework. By leveraging the built in support given to us by CreateErrorResponse, we can send validation information back to the client in ways that are JavaScript friendly. This gives the illusion of client side validation with the power of the server. It also removes the need to write validation rules twice (once on the client, and again on the server), and that is a benefit I think we can all appreciate!

BDN