ASP.NET MVC WebAPI - Optional parameters

ASP.NET WebAPI is a powerful tool for creating APIs quickly and efficiently in .NET. In fact, it takes minimal effort to expose your data through WebAPI though this is both a curse and a blessing. Blessing because it's so easy, curse because you need to be very careful of what you expose. You need to ensure that you're not exposing unwanted information and only provide authenticated access when necessary. Securing WebAPI is a big subject so I'll leave that for another post. Today, I'll show you how to create WebAPI controller methods that take optional parameters.

1. Using default values

This method is pretty self-explanatory. If you want to have optional parameters, you need to define a default value for those parameters. The best way to show this is with an example:

[HttpGet]
public IHttpActionResult GetStudents(string firstName = "jonh", string lastName = "smith")  
{
    var students = studentService.GetStudent(firstName, lastName);
    return Ok(students);
}

This API endpoint can be called like this:

http://yourwebsite/api/getstudents  
http://yourwebsite/api/getstudents?firstname=mary  
http://yourwebsite/api/getstudents?firstname=mary&lastname=jones  

The first call will return all students that have a first name of John and last name of Smith using the default values.

The second call will return all students with first name equal to Mary and last name Smith, i.e the default surname.

The final call will use the url parameters to return all students that match the values passed.

2. Using nullable parameters

The previous example will work, however it's not particularly practical. Default values are not particularly flexible. A better way to implement optional parameters is through the use of nullable parameters. Consider the example below:

[HttpGet]
public IHttpActionResult GetStudents(string? firstName = null, string? lastName = null, int? age = null)  
{
    //GetStudent() method checks for nulls and returns the appropriate result    
    var students = studentService.GetStudent(firstName, lastName, age);
    return Ok(students);
}

We can use the same URLs as in the previous example plus this one to filter by age as well:

http://yourwebsite/api/getstudents?firstname=mary&lastname=jones&age=13  

This time we should expect to get different results depending on the internal implementation of GetStudents()

3. Using parameter binding

A third and final way is using parameter binding to retrieve the URL parameters and act accordingly. We can expand the previous example like this:

[HttpGet]
public IHttpActionResult GetStudents([FromUri]StudentQuery query)  
{
    //GetStudent() method checks for nulls and returns the appropriate result    
    var students = studentService.GetStudent(firstName, lastName, age);
    return Ok(students);
}

// somewhere in your solution e.g. /WebAPI/Queries
public class StudentQuery  
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
}

This last method can be invoked using the same URLs as before but it takes advantage of binding to provide strongly typed parameters to your method(s). If your methods have more than 2 parameters then I would recommend taking advantage of parameter bindings to keep your code clean and easy to manage. Plus, you could reuse the same DTO/Query object for GET and POST methods which is a great bonus.

I hope you found this useful, but feel free to leave your comments/questions below.


  • Share this post on
comments powered by Disqus