ASP.NET Tutorial : When to Utilize Path and Query String Parameters?

The industry standard for developing and using web services is now RESTful APIs. Selecting how to organize the URLs and parameters is a crucial step in the architecture of REST APIs. Path parameters and query string parameters are the two most used methods for passing parameters to APIs. This blog will outline the distinctions between the two approaches, suggest situations in which to apply each, and offer examples to support each.

Parameters for Query Strings
Query String Parameters: What Are They?
Key-value pairs that are added to the end of a URL after a question mark (?) are known as query string parameters. An ampersand (&) is used to separate multiple parameters. They are frequently applied to paginate, sort, and filter data.

Example of Query String Parameters

Here’s a simple example of a query string parameter used to filter results:

GET /api/products?category=electronics&sort=price

In this example.

• category is a query parameter used to filter products by the electronics category.
• sort is a query parameter used to sort products by price.

When to use Query String Parameters?

1. Filtering: When you need to filter a list of items based on certain criteria.
2. Sorting: When you need to sort a list of items.
3. Pagination: When you need to paginate through a list of items (e.g., page=2&limit=20).
4. Optional Parameters: When parameters are optional and may not always be provided.

Example in .NET Core

Here’s an example of how you might handle query string parameters in an ASP.NET Core controller:

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetProducts([FromQuery] string category, [FromQuery] string sort)
    {
        // Example logic to filter and sort products
        var products = GetProductsFromDatabase();
        if (!string.IsNullOrEmpty(category))
        {
            products = products.Where(p => p.Category == category).ToList();
        }
        if (!string.IsNullOrEmpty(sort))
        {
            products = sort switch
            {
                "price" => products.OrderBy(p => p.Price).ToList(),
                _ => products
            };
        }
        return Ok(products);
    }
    private List<Product> GetProductsFromDatabase()
    {
        // Placeholder method to get products from a database
        return new List<Product>
        {
            new Product { Id = 1, Name = "Laptop", Category = "electronics", Price = 1000 },
            new Product { Id = 2, Name = "Phone", Category = "electronics", Price = 500 },
            // More products...
        };
    }
}
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Category { get; set; }
    public decimal Price { get; set; }
}

Path Parameters

What are Path Parameters?

Path parameters are part of the URL path itself and are used to identify a specific resource. They are embedded directly into the URL and are often used to retrieve, update, or delete a specific resource.

Example of Path Parameters

Here’s an example of a path parameter used to retrieve a specific product by its ID:

GET /api/products/123

In this example.

123 is a path parameter used to specify the ID of the product to retrieve.

When to Use Path Parameters?

1. Resource Identification: When the parameter is needed to identify a specific resource.
2. Mandatory Parameters: When the parameter is required to complete the request.

Example in .NET Core

Here’s an example of how you might handle path parameters in an ASP.NET Core controller.

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult GetProductById(int id)
    {
        // Example logic to retrieve a product by ID
        var product = GetProductFromDatabase(id);
        if (product == null)
        {
            return NotFound();
        }
        return Ok(product);
    }
    private Product GetProductFromDatabase(int id)
    {
        // Placeholder method to get a product from a database
        var products = new List<Product>
        {
            new Product { Id = 1, Name = "Laptop", Category = "electronics", Price = 1000 },
            new Product { Id = 2, Name = "Phone", Category = "electronics", Price = 500 },
            // More products...
        };
        return products.FirstOrDefault(p => p.Id == id);
    }
}

Combining Query String and Path Parameters

It’s often useful to combine both query string and path parameters in a single API. For example, you might use a path parameter to identify a specific resource and query string parameters to filter or sort related data.

Example

Here’s an example of an API that retrieves orders for a specific customer (identified by a path parameter) and supports filtering by order status (using a query string parameter).

GET /api/customers/123/orders?status=shipped

Example in .NET Core

Here’s how you might implement this in an ASP.NET Core controller.

[ApiController]
[Route("api/[controller]")]
public class CustomersController : ControllerBase
{
    [HttpGet("{customerId}/orders")]
    public IActionResult GetCustomerOrders(int customerId, [FromQuery] string status)
    {
        // Example logic to retrieve orders for a specific customer and filter by status
        var orders = GetOrdersFromDatabase(customerId);

        if (!string.IsNullOrEmpty(status))
        {
            orders = orders.Where(o => o.Status == status).ToList();
        }
        return Ok(orders);
    }
    private List<Order> GetOrdersFromDatabase(int customerId)
    {
        // Placeholder method to get orders from a database
        return new List<Order>
        {
            new Order { Id = 1, CustomerId = 123, Status = "shipped", Total = 50.00m },
            new Order { Id = 2, CustomerId = 123, Status = "processing", Total = 100.00m },
            // More orders...
        };
    }
}
public class Order
{
    public int Id { get; set; }
    public int CustomerId { get; set; }
    public string Status { get; set; }
    public decimal Total { get; set; }
}

Conclusion

Understanding when to use query string parameters and path parameters is crucial for designing intuitive and effective REST APIs. Query string parameters are ideal for filtering, sorting, and pagination, while path parameters are used for resource identification. Combining both can provide a flexible and powerful way to interact with your APIs.

By following the guidelines and examples provided in this blog, you can design well-structured REST APIs that are easy to use and maintain.

Windows Hosting Recommendation

HostForLIFEASP.NET receives Spotlight standing advantage award for providing recommended, cheap and fast ecommerce Hosting including the latest Magento. From the leading technology company, Microsoft. All the servers are equipped with the newest Windows Server 2022 R2, SQL Server 2022, ASP.NET Core 7.0.10 , ASP.NET MVC, Silverlight 5, WebMatrix and Visual Studio Lightswitch. Security and performance are at the core of their Magento hosting operations to confirm every website and/or application hosted on their servers is highly secured and performs at optimum level. mutually of the European ASP.NET hosting suppliers, HostForLIFE guarantees 99.9% uptime and fast loading speed. From €3.49/month , HostForLIFE provides you with unlimited disk space, unlimited domains, unlimited bandwidth,etc, for your website hosting needs.