Introduction to Query Parameters: Modifying API Behavior

Previously in this course, we implemented versioned routes in our URL-based Versioning Strategy: Implementing /v1/ Routes, ensuring our Task Manager API remains stable as it evolves. Now that we have a solid versioned foundation, we need to make our endpoints more useful.

In this lesson, we introduce Query Parameters, the standard way to modify the behavior of a request—specifically for filtering and sorting collections—without creating new, confusing URL paths.

What are Query Parameters?

Query parameters are key-value pairs appended to the end of a URL, starting with a question mark (?). They allow the client to send additional information to the server that doesn't define the resource itself, but rather how the resource should be returned.

Think of the URL path as the "noun" (the resource) and the query parameters as the "adjectives" (the modifiers).

The Anatomy of a Query String

A URL with query parameters follows a specific syntax: https://api.example.com/v1/tasks?status=completed&sort=due_date

• ?: The separator between the path and the query string.
• key=value: The parameters. status is the key, completed is the value.
• &: The delimiter used to chain multiple parameters together.

Why Use Query Parameters?

If we want to fetch only "completed" tasks, we could create a new endpoint like /v1/tasks/completed. However, as your API grows, this leads to "route explosion"—you’d eventually need /v1/tasks/completed/by-user/123/sorted-by-date.

Query parameters keep your path structure clean and follow the principles we discussed in Introduction to HTTP Methods: Mastering CRUD in REST APIs by keeping the endpoint focused on the tasks collection.

Use Cases: Filtering and Sorting

Query parameters are most commonly used for two operations that don't fundamentally change the resource, but change the view of that resource.

1. Filtering

Filtering reduces the number of items returned based on specific criteria.

• Example: GET /v1/tasks?priority=high
• Result: Returns only tasks where the priority field matches "high".

2. Sorting

Sorting dictates the order of the returned collection.

• Example: GET /v1/tasks?sort=created_at
• Result: Returns the tasks ordered by their creation date.

Worked Example: Parsing a Query

In a typical Node.js/Express environment, accessing these parameters is straightforward. The framework parses the query string into a JavaScript object for you.

JAVASCRIPT
// GET /v1/tasks?status=pending
app.get(CE9178">'/v1/tasks', (req, res) => {
    const { status } = req.query; 
    
    if (status) {
        // Logic to filter tasks from the database where task.status === status
        console.log(CE9178">`Filtering by: ${status}`);
    }
    
    res.json({ message: "Task list retrieved" });
});

When the client hits GET /v1/tasks?status=pending, req.query becomes { status: 'pending' }. You can then pass this object directly to your database query.

Hands-on Exercise

In your Task Manager API project, navigate to your /v1/tasks route handler.

1. Log the req.query object to the console.
2. Fire a request using your browser or a tool like Postman: http://localhost:3000/v1/tasks?user_id=5&category=work.
3. Observe the output in your server terminal. You should see { user_id: '5', category: 'work' }.

Common Pitfalls

• Complex Nested Objects: Don't try to pass entire JSON objects in query parameters. They are meant for flat, simple key-value pairs. If you need to send a complex object, use the request body (typically in a POST or PUT request).
• Sensitive Data: Never pass passwords, API keys, or personal identifiers in query parameters. URLs are often logged in plain text by browsers, proxies, and server logs. Use headers for authentication, as covered in our REST API Design: Implementing Filtering and Sorting Best Practices.
• Reserved Characters: If your parameter values contain spaces or special characters (like & or =), they must be URL-encoded (e.g., a space becomes %20). Most modern HTTP clients handle this automatically.

FAQ

Q: Can I use query parameters with POST requests? A: Technically yes, but it is rare. Query parameters are intended to modify GET requests for collections. For POST requests, place your data in the request body.

Q: How many query parameters can I add to one URL? A: There is no hard limit defined by the HTTP spec, but web servers and browsers have limits on total URL length (often around 2,000 characters). Keep them concise.

Q: Are query parameter keys case-sensitive? A: Yes. ?status=open and ?Status=open are different keys. Always standardize your API to use lowercase keys.

Recap

Query parameters are the "adjectives" of your API. They allow clients to filter and sort data collections while keeping your URL paths clean and predictable. By using req.query in your route handlers, you can dynamically adjust the data returned to the user without bloating your route definitions.

Up next: We will dive deeper into Filtering Collections by implementing actual status-based filtering logic in our Task Manager API.