Parameter binding in Web API

Learn how parameter binding (the process of setting values to parameters of the Web API controller methods) works and the best practices

ASP.Net Web API is a lightweight framework that can be used for building RESTful HTTP services. When working with controller methods in Web API, you would often need to pass parameters to those methods. A “parameter” here refers to the argument to a method. Parameter binding is defined as the process of setting values to parameters of the Web API methods.

TypeConverters and ModelBinders

Note that there are two ways in which Web API can bind parameters: model binding and formatters. While the first technique is used to read from the query string, the second technique is used to read from the request body.  You can also use type converters to enable Web API to treat a class as a simple type and then bind the parameter from the Uri. To do this, you would need to create a custom TypeConverter. You can also create a custom model binder by implementing the IModelBinder interface in your class and then implementing the BindModel method. I'll discuss more on type converters and model binders in a later post, but until then, you can take a look at this article for more information.

Now, in order to bind parameters, Web API follows this rule: for simple types, it tries to get the value from the Uri, while for complex types, it tries to get the value from the request body. Note that simple types here refers to the .Net primitive types that include int, bool, double, float, etc., and also other types that include, TimeSpan, DateTime, Guid, decimal, and string. It also includes any type for which a type converter is available that can convert from a string. In the next section we’ll explore how and when to use the [FromBody] and [FromUri] attributes.

When should I use the FromBody and FromUri attributes?

If you've been using Web API for some time, you should be familiar with the [FromBody] and [FromUri] attributes. If not, read this section to gain an understanding on how it works. While the [FromUri] attribute is prefixed to the parameter to specify that the value should be read from the Uri of the request, the [FromBody] attribute is used to specify that the value should be read from the body of the request.

Here's the default behavior of Web API. For all primitive types (int, double, float, etc.) the Web API runtime attempts to read the value from the Uri of the HTTP request. For complex types (instances of classes), the Web API runtime tries to read the value from the body of the HTTP request using a media-type formatter.

Hence, if you have a value in the request Uri that is of primitive type, you don't need to specify the [FromUri] attribute. Similarly, if you have a value in the request body that is of complex type, you don't need to specify the [FromBody] attribute. However, if the primitive type resides in the request body or the complex type resides in the request Uri, you would have to specify the [FromBody] and [FromUri] attributes respectively. The reason is that you are changing the default behavior in both cases.

The following code snippet illustrates how you can specify the [FromBody] attribute for a fundamental data type passed as a parameter to a Web API method.

public class SecurityController : ApiController

{

    public HttpResponseMessage Post([FromBody]int id)

    {

       //Write your code here

    }

}

And here's a code snippet that illustrates how you can pass a complex type as a parameter to a Web API method using the FromUri attribute.

public class SecurityController : ApiController

{

    public HttpResponseMessage Post([FromUri]User user)

    {

       //Write your code here

    }

}

It should be noted that sending user authentication data like username and password through the Url is not a good practice even if you might be using SSL. This is because such data might be saved in your browser logs and hence it is not at all a desirable practice. For passing such sensitive data (this might even include credit card information, etc.) via the request body. Hence it is imperative to use [FromBody] in such cases.

Note that when you use the [FromBody] attribute while passing a parameter to a Web API method, the Web API runtime takes advantage of the content type header to select the correct formatter. You can learn more on content negotiation from my article here.

This article is published as part of the IDG Contributor Network. Want to Join?

To comment on this article and other InfoWorld content, visit InfoWorld's LinkedIn page, Facebook page and Twitter stream.
From CIO: 8 Free Online Courses to Grow Your Tech Skills
Notice to our Readers
We're now using social media to take your comments and feedback. Learn more about this here.