Binding Parameters
The discussion above about “body values” and “non-body values” leads us to discuss Formatters and Model Binders, since those two classes are responsible for handling bodies and non-body values, respectively. When you write an action method signature and include parameters, complex types come from “the body,” which really means that formatters are responsible for generating them; simple types, on the other handle, come from “not the body,” which means that model binders are responsible for generating them. For body content being sent, we use formatters to decode the data.
To tell the whole story, though, we need to rise up a level into a concept that is new to Web API: Parameter Binding. Web API uses parameter binders to determine how to provide values for individual parameters. Attributes can be used to influence that decision (like [ModelBinder], an attribute we've seen before with MVC), but the default logic uses the simple type vs. complex type logic when there are no overrides applied to influence the binding decision.
The parameter binding system looks to the action's parameters to find any attributes which derive from ParameterBindingAttribute. There are a few such attributes built into Web API, as shown in Table 11.1. In addition, you can register custom parameter binders which do not use model binding or formatters, either by registering them in the configuration or by writing your own ParameterBindingAttribute-based attributes.
Table 11.1 Parameter Binding Attributes
| Attribute | Meaning |
| ModelBindingAttribute | This tells the parameter binding system to use model binding (meaning, create the value through the use of any registered model binders and value providers).
This is what is implied by the default binding logic for any parameter of a simple type. |
| FromUriAttribute | This is a specialization of ModelBindingAttribute that tells the system only to use value providers from factories which implement IUriValueProviderFactory to limit the values bound to ensure that they come only from URI.
Out of the box, the route data and query string value providers in Web API implement this interface. |
| FromBodyAttribute | This tells the parameter binding system to use formatters (meaning, create the value by finding an implementation of MediaTypeFormatter which can decode the body and create the given type from the decoded body data).
This is what is implied by the default binding logic for any complex type. |
The parameter binding system is quite different from the way MVC works. In MVC, all parameters are created through model binding. Model binding in Web API works mostly the same way as MVC (model binders and providers, and value providers and factories), although it's been re-factored quite a bit, based on the alternate model binding system from MVC Futures. You will find built-in model binders for arrays, collections, dictionaries, simple types, and yes, even complex types (though you would need to use [ModelBinder] to get them to run, obviously). Although the interfaces have changed slightly, if you know how to write a model binder or value provider in MVC, you'll be right at home doing the same thing for Web API.
Formatters are a new concept for Web API. Formatters are responsible for both consuming and producing body content. You can think of formatters in much the same way you might think of serializers in .NET: classes which are responsible for encoding and decoding custom complex types into and out of the stream of bytes, which is the body content. You can encode exactly one object into the body, and decode exactly one object back out of the body (although that object can contain nested objects, as you'd expect of any complex type in .NET).
Built into Web API you will find three formatters: one which encodes and decodes JSON (using Json.NET), one which encodes and decodes XML (using either DataContractSerializer or XmlSerializer), and one which decodes form URL encoded from data in the body from a browser form post. Each of these formatters is quite powerful, and will make its best effort to transcode its supported format into the class of your choosing.