WEB API 2 EXPLORING PARAMETER BINDING


This article demonstrates how to call or map Web API methods with different types of parameters using XML, Json and Urlencoded formats. It shows how simple parameters, objects parameters and array parameters can be sent either in the body of the Http request or in the Url itself. This all works per default in Web API and if that’s not enough, you can customize it yourself.

code: https://github.com/damienbod/WebApiParameters

Simple Parameters

Example 1: Sending a simple parameter in the Url

1
2
3
4
5
6
7
8
9
10
11
[RoutePrefix("api/values")]
public class ValuesController : ApiController
{
  [Route("example1")]
  [HttpGet]
  public string Get(int id)
  {
     return "value";
  }
}

Example 2: Sending simple parameters in the Url

1
2
3
4
5
6
7
[Route("example2")]
[HttpGet]
public string GetWith3Parameters(int id1, long id2, double id3)
{
    return "value";
}

Example 3: Sending simple parameters using attribute routing

1
2
3
4
5
6
7
[Route("example3/{id1}/{id2}/{id3}")]
[HttpGet]
public string GetWith3ParametersAttributeRouting(int id1, long id2, double id3)
{
   return "value";
}

Example 4: Sending an object in the Url

1
2
3
4
5
6
7
[Route("example4")]
[HttpGet]
public string GetWithUri([FromUri] ParamsObject paramsObject)
{
  return "value:" + paramsObject.Id1;
}

Example 5: Sending an object in the Request body

1
2
3
4
5
6
[Route("example5")]
[HttpPost]
public string GetWithBody([FromBody] ParamsObject paramsObject)
{
  return "value:" + paramsObject.Id1;
}

Calling the method using Urlencoded in the body:

1
2
3
4
5
6
User-Agent: Fiddler
Host: localhost:49407
Content-Length: 32
Content-Type: application/x-www-form-urlencoded
id1=1&id2=2&id3=3

WebApiParams_01

Calling the method using Json in the body:

1
2
3
4
5
6
User-Agent: Fiddler
Host: localhost:49407
Content-Length: 32
Content-Type: application/json
{ "Id1" : 2, "Id2": 2, "Id3": 3}

WebApiParams_02

Calling the method using XML in the body

This requires extra code in the Global.asax

1
2
3
4
protected void Application_Start()
{
   var xml = GlobalConfiguration.Configuration.Formatters.XmlFormatter;
   xml.UseXmlSerializer = true;

The client request is as follows:

1
2
3
4
5
6
User-Agent: Fiddler
Content-Type: application/xml
Host: localhost:49407
Content-Length: 65
<ParamsObject><Id1>7</Id1><Id2>8</Id2><Id3>9</Id3></ParamsObject>

WebApiParams_03

Arrays and Lists

Example 6: Sending a simple list in the Url

1
2
3
4
5
6
7
8
9
10
11
12
[Route("example6")]
[HttpGet]
public string GetListFromUri([FromUri] List<int> paramsObject)
{
  if (paramsObject != null)
  {
    return "recieved a list with length:" + paramsObject.Count;
  }
  return "NOTHING RECIEVED...";
}

Example 7: Sending an object list in the Body

1
2
3
4
5
6
7
8
9
10
11
12
[Route("example8")]
[HttpPost]
public string GetListFromBody([FromBody] List<ParamsObject> paramsList)
{
  if (paramsList != null)
  {
     return "recieved a list with length:" + paramsList.Count;
  }
  return "NOTHING RECIEVED...";
}

Calling with Json:

1
2
3
4
5
6
User-Agent: Fiddler
Content-Type: application/json
Host: localhost:49407
Content-Length: 91
[{"Id1":3,"Id2":76,"Id3":19},{"Id1":56,"Id2":87,"Id3":94},{"Id1":976,"Id2":345,"Id3":7554}]

WebApiParams_05_json

Calling with XML:

1
2
3
4
5
6
7
8
9
10
User-Agent: Fiddler
Content-Type: application/xml
Host: localhost:49407
Content-Length: 258
<ArrayOfParamsObject>
<ParamsObject><Id1>3</Id1><Id2>76</Id2><Id3>19</Id3></ParamsObject>
<ParamsObject><Id1>56</Id1><Id2>87</Id2><Id3>94</Id3></ParamsObject>
<ParamsObject><Id1>976</Id1><Id2>345</Id2><Id3>7554</Id3></ParamsObject>
</ArrayOfParamsObject>

WebApiParams_04_xml

Example 8: Sending object lists in the Body

1
2
3
4
5
6
7
8
9
10
11
[Route("example8")]
[HttpPost]
public string GetListsFromBody([FromBody] List<List<ParamsObject>> paramsList)
{
  if (paramsList != null)
  {
    return "recieved a list with length:" + paramsList.Count;
  }
  return "NOTHING RECIEVED...";
}

This is a little bit different to the previous examples. The body can only send one single object to Web API. Because of this, the lists of objects are wrapped in a list or a parent object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
User-Agent: Fiddler
Content-Type: application/json
Host: localhost:49407
Content-Length: 185
[
 [
  {"Id1":3,"Id2":76,"Id3":19},
  {"Id1":56,"Id2":87,"Id3":94},
  {"Id1":976,"Id2":345,"Id3":7554}
 ],
 [
  {"Id1":3,"Id2":76,"Id3":19},
  {"Id1":56,"Id2":87,"Id3":94},
  {"Id1":976,"Id2":345,"Id3":7554}
 ]
]

Customizing the parameters

What if the default parameter binding is not enough? Then you can use the ModelBinder class to change your parameters and create your own parameter formats. You could also use ActionFilters for this. Many blogs exist which already explains how to use the ModelBinder class. See the links underneath.

Files and binaries

Files or binaries can also be sent to Web API methods. The article demonstrates how to do this.

Links:

http://aspnet.codeplex.com/SourceControl/latest#Samples/WebApi/CustomParameterBinding/

http://www.asp.net/web-api/overview/formats-and-model-binding/parameter-binding-in-aspnet-web-api

http://www.strathweb.com/2013/04/asp-net-web-api-parameter-binding-part-1-understanding-binding-from-uri/

http://www.roelvanlisdonk.nl/?p=3505

http://stackoverflow.com/questions/9981330/how-to-pass-an-array-of-integers-to-a-asp-net-web-api-rest-service

http://stackoverflow.com/questions/14628576/passing-an-json-array-to-mvc-web-api-via-get

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s