ASP.NET Core – Four basic ways to receive parameters

There are four basic ways to receive parameters in an ASP.NET Core Web API: query strings, path parameters, request body, and request headers. I’ll show examples of these below.

Query string parameters

Let’s say you have two query string keys: name and servings. To add these query string parameters, add method parameters with names that match the query string key names (name and servings):

[ApiController] [Route("[controller]")] public class RecipeController : ControllerBase { [HttpGet()] public Recipe Get(string name, int servings) { return new Recipe() { Name = name, Servings = servings }; } }
Code language: C# (cs)

Now send a request with query string keys and values:

GET /Recipe?name=pizza&servings=4
Code language: plaintext (plaintext)

The values from the query string are mapped to the method parameters (name, servings), and it returns the following 200 (OK) response:

{ "name": "pizza", "servings": 4 }
Code language: JSON / JSON with Comments (json)

You can map the query string to a complex type by explicitly adding the [FromQuery] attribute:

[HttpGet()] public Recipe Get([FromQuery]Recipe recipe) { return recipe; }
Code language: C# (cs)

For more details on getting values from query strings, read here: ASP.NET Core – Getting query string values.

Path parameters

To add path parameters, configure the route (in the HttpGet attribute) with the parameter names, and then add method parameters with matching names:

[ApiController] [Route("[controller]")] public class RecipeController : ControllerBase { [HttpGet("{name}/{servings}")] public Recipe Get(string name, int servings) { return new Recipe() { Name = name, Servings = servings }; } }
Code language: C# (cs)

Now send a request with the parameter values as part of the path:

GET /Recipe/soup/8
Code language: plaintext (plaintext)

The values from the path are mapped to the method parameters and it returns the following 200 (OK) response:

{ "name": "soup", "servings": 8 }
Code language: JSON / JSON with Comments (json)

If you want to map path parameters to a complex type (instead of having several simple type parameters), use the [FromRoute] attribute:

[HttpGet("{name}/{servings}")] public Recipe Get([FromRoute]Recipe recipe) { return recipe; }
Code language: C# (cs)

Request body

When you have multiple parameters, it’s common to encapsulate them in a complex type and get them from the request body. To do that, add the complex type as a method parameter:

[ApiController] [Route("[controller]")] public class RecipeController : ControllerBase { [HttpPost()] public IActionResult Post(Recipe recipe) { return Ok($"Posted {recipe.Name}"); } }
Code language: C# (cs)

Now send the request with JSON in the body:

POST /Recipe Content-Type: application/json Body: { "name": "steak", "servings": 1 }
Code language: plaintext (plaintext)

The JSON from the request body is deserialized and mapped to the Recipe parameter. It returns a 200 (OK) response with the following:

Posted steak
Code language: plaintext (plaintext)

Request headers

Sometimes it’s useful to send parameters via request headers. These are often used in addition to other parameters. To add a request header parameter, add a method parameter with the same name as the header, and apply the [FromHeader] attribute to it.

[ApiController] [Route("[controller]")] public class RecipeController : ControllerBase { [HttpGet("{name}/{servings}")] public Recipe Get(string name, int servings, [FromHeader]bool includeImageUrl) { string imageUrl = null; if (includeImageUrl) imageUrl = $"{name}.png"; return new Recipe() { Name = name, Servings = servings, ImageUrl = imageUrl }; } }
Code language: C# (cs)

Now send a request and include the header:

GET /Recipe/cake/20 Headers: IncludeImageUrl=true
Code language: plaintext (plaintext)

In addition to mapping the path parameters (name and servings), it mapped the request header to the includeImageUrl parameter and returned the following 200 (OK) response:

{ "name": "cake", "servings": 20, "imageUrl": "cake.png" }
Code language: JSON / JSON with Comments (json)

For more details on getting request headers, read here: ASP.NET Core – How to get request headers

Further reading

This was meant to be an introduction to the basic ways of receiving parameters. For more advanced scenarios, you may want to check these out:

Furthermore, I highly suggest understanding and using model validation attributes to guard against bad input.

Leave a Comment