.NET Core API Parameters – MSDN Documentation

Introduction

Understanding how to define and use parameters is essential when building robust .NET Core APIs. This page covers the most common parameter types, conventions, and best practices.

Parameter Types

Type	Description	Example
`string`	Textual data. Often used for identifiers or descriptive fields.	`public IActionResult Get([FromQuery] string id)`
`int`	Integer numeric value. Frequently used for pagination or IDs.	`public IActionResult Get([FromQuery] int page = 1)`
`bool`	Boolean flag. Indicates true/false options.	`public IActionResult Get([FromQuery] bool includeDetails)`
`enum`	Enumerated set of named constants. Improves readability.	`public IActionResult Get([FromQuery] SortOrder order)`
`DateTime`	Timestamp value. Used for date ranges or logs.	`public IActionResult Get([FromQuery] DateTime? since)`
`CancellationToken`	Signals request cancellation. Should be the last optional parameter.	`public async Task GetAsync(CancellationToken ct)`
`IFormFile`	File upload via multipart/form-data.	`public async Task Upload([FromForm] IFormFile file)`
`Complex Model`	Custom class representing a DTO. Enables model binding.	`public IActionResult Create([FromBody] ProductDto dto)`

Optional Parameters & Default Values

Mark parameters as optional by providing a default value. Optional parameters must appear after required ones.

public IActionResult Search(
    [FromQuery] string query,
    [FromQuery] int page = 1,
    [FromQuery] int pageSize = 20)
{
    // implementation
}

Special Attributes

[FromQuery] – Binds values from the query string.
[FromRoute] – Binds values from the URL route.
[FromBody] – Binds values from the request body (JSON, XML, etc.).
[FromHeader] – Binds values from HTTP headers.
[FromForm] – Binds values from form-data or multipart uploads.

Best Practices

Prefer explicit binding attributes to avoid ambiguities.
Use nullable types for optional values when possible.
Validate complex models with [ApiController] and data annotations.
Document each parameter using XML comments.
Keep the number of parameters low; consider wrapping related values in a DTO.

Example Endpoint

/// <summary>
/// Retrieves a filtered list of products.
/// </summary>
/// <param name="category">Category filter.</param>
/// <param name="minPrice">Minimum price (optional).</param>
/// <param name="maxPrice">Maximum price (optional).</param>
/// <param name="includeOutOfStock">Include out‑of‑stock items.</param>
/// <returns>Paged list of products.</returns>
[HttpGet("products")]
public async Task<IActionResult> GetProducts(
    [FromQuery] string category,
    [FromQuery] decimal? minPrice = null,
    [FromQuery] decimal? maxPrice = null,
    [FromQuery] bool includeOutOfStock = false,
    CancellationToken ct = default)
{
    var result = await _service.GetProductsAsync(category, minPrice, maxPrice,
        includeOutOfStock, ct);
    return Ok(result);
}