Parameter Binding

In the previous section we learned how Web API routes HTTP request to a controller and action method. Here, we will learn how Web API binds HTTP request data to the parameters of an action method.

Action methods in Web API controller can have one or more parameters of different types. It can be either primitive type or complex type. Web API binds action method parameters either with URL's query string or with request body depending on the parameter type. By default, if parameter type is of .NET primitive type such as int, bool, double, string, GUID, DateTime, decimal or any other type that can be converted from string type then it sets the value of a parameter from the query string. And if the parameter type is complex type then Web API tries to get the value from request body by default.

The following table lists the default rules for parameter binding.

HTTP Method	Query String	Request Body
GET	Primitive Type, Complex Type	NA
POST	Primitive Type	Complex Type
PUT	Primitive Type	Complex Type
PATCH	Primitive Type	Complex Type
DELETE	Primitive Type, Complex Type	NA

Let's see how Web API get values of action method parameters from HTTP request.

Get Action Method with Primitive Parameter

Consider the following example of Get action method that includes single primitive type parameter.

Example: Primitive Parameter Binding

public class StudentController : ApiController
{
                        public Student Get(int id) 
    {
              
    }
}

As you can see above Get action method includes id parameter of int type. So, Web API will try to extract the value of id from the query string of requested URL, convert it into int and assign it to id parameter of Get action method. For example, if an HTTP request is http://localhost/api/student?id=1 then value of id parameter will be 1.

Followings are valid HTTP GET Requests for the above action method.

http://localhost/api/student?id=1

http://localhost/api/student?ID=1

Note:

Query string parameter name and action method parameter name must be the same (case-insensitive). If names do not match then values of the parameters will not be set. The order of the parameters can be different.

Multiple Primitive Parameters

Consider the following example of Get action method with multiple primitive parameters.

Example: Multiple Parameters Binding

public class StudentController : ApiController
{
                        public Student Get(int id, string name) 
    {
    }
}

As you can see above, Get method includes multiple primitive type parameters. So, Web API will try to extract the values from the query string of request URL. For example, if an HTTP request is http://localhost/api/student?id=1&name=steve then value of id parameter will be 1 and name will be "steve".

Followings are valid HTTP GET Requests for the above action method.

http://localhost/api/student?id=1&name=steve

http://localhost/api/student?ID=1&NAME=steve

http://localhost/api/student?name=steve&id=1

Note:

Query string parameter names must match with the name of an action method parameter. However, they can be in different order.

POST Action Method with Primitive Parameter

HTTP POST request is used to create new resource. It can include request data into HTTP request body and also in query string.

Consider the following Post action method.

Example: Post Method with Primitive Parameter

public class StudentController : ApiController
{
                        public Student Post(id id, string name)
    {
           
    }
}

As you can see above, Post() action method includes primitive type parameters id and name. So, by default, Web API will get values from the query string. For example, if an HTTP POST request is http://localhost/api/student?id=1&name=steve then the value of id will be 1 and name will be "steve" in the above Post() method.

Now, consider the following Post() method with complex type parameter.

Example: Post Method with Complex Type Parameter

public class Student
{
                        public int Id { get; set; }
                        public string Name { get; set; }
}
public class StudentController : ApiController
{
                        public Student Post(Student stud)
    {
           
    }
}

The above Post() method includes Student type parameter. So, as a default rule, Web API will try to get the values of stud parameter from HTTP request body.

Following is a valid HTTP POST request in the fiddler for the above action method.

Web API will extract the JSON object from the Request body above and convert it into Student object automatically because names of JSON object properties matches with the name of Student class properties (case-insensitive).

POST Method with Mixed Parameters

Post action method can include primitive and complex type parameters. Consider the following example.

Example: Post Method with Primitive and Complex Type Parameters

public class Student
{
                        public int Id { get; set; }
                        public string Name { get; set; }
}
public class StudentController : ApiController
{
                        public Student Post(int age, Student student)
    {
    }
}

The above Post method includes both primitive and complex type parameter. So, by default , Web API will get the id parameter from query string and student parameter from the request body.

Webapi Tutorial