Path Parameters vs Query Parameters — When to Use Which

What You'll Learn

• The difference between path parameters and query parameters
• When to use each one
• How they appear in API documentation
• Common mistakes that break APIs

Why This Matters

Every API designer and API caller has to decide where to put each value — in the path or in the query string. Pick wrong and your API becomes inconsistent, hard to cache, and confusing to use. This lesson gives you a simple rule that works for almost every case.

Simple Explanation

Both path parameters and query parameters are values inside the URL. The difference is where they live and what they mean:

GET /users/123/posts?status=published&sort=date

• 123 is a path parameter — embedded in the path, identifies a specific resource.
• status=published and sort=date are query parameters — after the ?, modify how the resource is returned.

Path Parameters

A path parameter is a value embedded in the URL path. It usually identifies a specific resource or a sub-resource.

Examples

/users/123              → 123 is the user ID
/users/123/posts/456    → 123 is the user ID, 456 is the post ID
/orgs/acme/repos/api    → acme is the org name, api is the repo name

How APIs document them

API docs usually write path parameters with curly braces or a colon:

GET /users/{userId}
GET /users/:userId/posts/:postId

When to use a path parameter

• To identify a specific resource by ID or name.
• To identify a hierarchy (user → posts → comments).
• When the value is required — without it, the URL makes no sense.

Query Parameters

A query parameter is a key-value pair after the ? in the URL. It modifies how the server returns the resource — filters, sorts, pagination, options.

Examples

/users?role=admin                  → filter by role
/users?sort=name&order=desc        → sort by name descending
/posts?status=published&page=2     → filter + paginate
/search?q=hello+world              → search query

When to use a query parameter

• To filter a collection (only show some items).
• To sort the results.
• To paginate (page, limit, offset).
• When the value is optional.
• For search queries.

The Simple Rule

If the value identifies what resource you want, use a path parameter.
If the value modifies how the resource is returned, use a query parameter.

Quick test

Ask yourself: "Could I remove this value and the URL still makes sense?"

• /users/123 without the 123 → /users (different resource, but still meaningful). Path parameter.
• /users?role=admin without role=admin → /users (returns all users instead of just admins). Query parameter.

Side-by-Side Comparison

Combining Both

Most real API calls use both at once:

GET /users/123/posts?status=published&sort=date&page=2&limit=10

Translation: "On user 123's posts, give me page 2 (10 per page) of published posts, sorted by date."

• 123 — path param, identifies the user.
• status, sort, page, limit — query params, modify the result.

Common Mistakes

1. Using query params for resource IDs. /users?id=123 instead of /users/123. It works, but it breaks REST conventions and makes caching harder.
2. Using path params for filters. /users/active looks like "get user with ID 'active'". Use /users?status=active instead.
3. Mixing case. ?Role=admin and ?role=admin are different parameters. Pick lowercase and stick with it.
4. Not URL-encoding query values. ?q=Anita & Ravi breaks the URL. Use ?q=Anita%20%26%20Ravi.
5. Putting optional fields in the path. If include is optional, it belongs in the query, not the path: /users?include=posts, not /users/include/posts.

Practical Exercise (5 minutes)

For each scenario, decide: path parameter or query parameter?

1. Get user with ID 42.
2. Get all users who are admins.
3. Get the third page of posts, 20 per page.
4. Get post 99's comments.
5. Search posts for the word "API".
6. Get user 42's posts that are published, sorted by date.

Answers: 1. Path (/users/42). 2. Query (/users?role=admin). 3. Query (/posts?page=3&limit=20). 4. Path (/posts/99/comments). 5. Query (/posts?q=API). 6. Both (/users/42/posts?status=published&sort=date).

Mini Challenge

Design the URL for: "Get the 2nd page of comments on post 456, sorted by newest first, 10 per page, only showing comments with at least 5 likes." Write the full URL with path and query parameters.

Key Takeaways