Understand parameter binding in ASP.Net Web API

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 will often need to pass parameters to those methods. A “parameter” here simply refers to the argument to a method, while “parameter binding” refers to the process of setting values to the parameters of the Web API methods.

Note that there are two ways in which Web API can bind parameters: model binding and formatters. Model binding is used to read from the query string, while formatters are 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. For more on type converters and model binders, take a look at this Microsoft documentation.

Now, in order to bind parameters, Web API follows this rule: For simple types, Web API tries to get the value from the URI, and for complex types, Web API tries to get the value from the request body. The simple types here refer to both the .Net primitive types—int, bool, double, float, and so on—and to 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 the [FromBody] and [FromUri] attributes used to bind values from the request body and URI respectively.

When to use [FromBody] and [FromUri] in Web API

If you’ve been using Web API for some time, you may be familiar with the [FromBody] and [FromUri] attributes. The [FromUri] attribute is prefixed to the parameter to specify that the value should be read from the URI of the request, and the [FromBody] attribute is used to specify that the value should be read from the body of the request.

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. This is the default behavior of Web API. 

Hence, if you have a value in the request URI that is a primitive type, you don’t need to specify the [FromUri] attribute. Similarly, if you have a value in the request body that is a 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 must specify the [FromBody] or the [FromUri] attribute. The reason is that you are straying from the default behavior in both cases.

How to use [FromBody] and [FromUri] in Web API

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 URI is not a good practice, even if you might be using SSL. This is because such data might be saved to browser logs, where it is vulnerable to exposure. When passing any sensitive data (usernames, passwords, credit card information, etc.) via the request body, it is imperative to use [FromBody] in every case.

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 about content negotiation in Web API from my article here.