Path Parameter vs Query Parameter in REST: Key Differences and Usage

In REST APIs, path parameters are part of the URL path and identify a specific resource, while query parameters appear after a question mark and filter or modify the resource data. Path parameters are required and fixed, whereas query parameters are optional and flexible.

Quick Comparison

This table summarizes the main differences between path parameters and query parameters in REST APIs.

Factor	Path Parameter	Query Parameter
Location in URL	Part of the URL path (e.g., /users/{id})	After the ? in URL (e.g., ?sort=asc)
Purpose	Identify specific resource(s)	Filter, sort, or modify resource data
Required or Optional	Usually required	Usually optional
Multiple Values	Typically single value	Can have multiple values
Effect on Caching	Defines resource identity	Does not change resource identity but changes response
Example URL	/users/123	/users?role=admin&active=true

Key Differences

Path parameters are embedded directly in the URL path and are used to point to a specific resource or resource collection. For example, in /users/123, 123 is a path parameter identifying a user with ID 123. These parameters are mandatory because they define the resource being accessed.

On the other hand, query parameters come after a question mark ? in the URL and are used to filter, sort, or paginate the data returned by the server. For example, /users?role=admin filters users by the role 'admin'. Query parameters are optional and can be combined in any order.

Path parameters affect the resource's identity and are part of the URL structure, while query parameters modify the representation or subset of that resource without changing its identity. This distinction helps in designing clean, intuitive REST APIs.

Code Comparison

Example of using a path parameter to get a user by ID in a REST API using Express.js (Node.js):

javascript

import express from 'express';
const app = express();

// Route with path parameter :id
app.get('/users/:id', (req, res) => {
  const userId = req.params.id;
  res.send(`User ID requested: ${userId}`);
});

app.listen(3000, () => console.log('Server running on port 3000'));

Output

User ID requested: 123 (when accessing /users/123)

Query Parameter Equivalent

Example of using query parameters to filter users by role in the same Express.js API:

javascript

import express from 'express';
const app = express();

// Route with query parameter ?role
app.get('/users', (req, res) => {
  const role = req.query.role;
  if (role) {
    res.send(`Filtering users by role: ${role}`);
  } else {
    res.send('All users requested');
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

Output

Filtering users by role: admin (when accessing /users?role=admin)

When to Use Which

Choose path parameters when you need to specify a unique resource or resource group, such as a user ID or product code, because they clearly identify the resource in the URL. Use query parameters when you want to filter, sort, paginate, or modify the data returned from a resource without changing the resource itself. This keeps your API intuitive and RESTful.

For example, use /orders/456 to get order 456, but use /orders?status=shipped to get all orders with the status shipped.

Key Takeaways

Path parameters identify specific resources and are part of the URL path.

Query parameters filter or modify resource data and appear after a question mark in the URL.

Path parameters are usually required; query parameters are optional and flexible.

Use path parameters for resource identity and query parameters for filtering or sorting.

Clear use of both improves API design and usability.