Filtering Requests
The ability to filter requests with attributes has been in ASP.NET since version 1.0, and the ability to add global filters was added in MVC 3. ASP.NET Web API includes both features, although as discussed previously, the filter is global at the configuration level, not at the application level (as there are no such application-wide global features in Web API).
One of the improvements in Web API over MVC is that filters are now part of the asynchronous pipeline, and are by definition always async. If a filter could benefit from being asynchronous — for example, logging exception failures to an asynchronous data source like a database or the file system — then it can do so. However, the Web API team also realized that sometimes being forced to write asynchronous code is unnecessary overhead (especially if you're targeting .NET 4 and don't have access to async and await), so they also created synchronous attribute-based base class implementations of the three filter interfaces. When porting MVC filters, using these base classes is probably the simplest way to get started. If a filter needs to implement more than one stage of the filter pipeline (such as action filtering and exception filtering), there are no helper base classes and the interfaces need to be implemented explicitly.
Developers can apply filters at the action level (for a single action), at the controller level (for all actions in the controller), and at the configuration level (for all actions on all controllers in the configuration). Web API includes one filter in the box for developers to use, AuthorizeAttribute. Much like its MVC counterpart, this attribute is used to decorate actions that require authorization, and includes the AllowAnonymousAttribute, which can selectively “undo” the AuthorizeAttribute. The Web API team is also releasing an out-of-band NuGet package to support several OData-related features, including QueryableAttribute, which can automatically support OData query syntax (like the $top and $filter query string values).
Filter Interfaces and Base Classes
| Asynchronous Interface Synchronous Base Class | Purpose |
| IAuthorizationFilter AuthorizationFilterAttribute | Authorization filters run before any parameter binding has happened. They are intended to filter out requests which do not have the proper authorization for the action in question.
Authorization filters run before action filters. |
| IActionFilter ActionFilterAttribute | Action filters run after parameter binding has happened and wraps the call to the API action method, allowing interception before the action has been dispatched to and after it is done executing. They are intended to allow developers to either augment and/or replace the incoming values and/or outgoing results of the action. |
| IExceptionFilter ExceptionFilterAttribute | Exception filters are called when calling the action resulted in an exception being thrown. Exception filters can inspect the exception and take some action (for example logging); it can also opt to handle the exception by providing a new response object. |
There is no equivalent to the MVC HandleError attribute in Web API. MVC's default behavior for errors is to return the ASP.NET “yellow screen of death,” which is appropriate (if not entirely user friendly) when your application is generating HTML. The HandleError attribute allows MVC developers to replace that behavior with a custom view. Web API, on the other hand, should always attempt to return structured data, including when error conditions occur, so it has built-in support for serializing errors back to the end user. Developers who wish to override this behavior can write their own error handler filter and register it at the configuration level.