Query parameters vs path parameters: what's the difference?

Look at almost any API URL and you'll see two kinds of value mixed into it:

GET https://api.example.com/customers/42/orders?status=open&limit=10

42 is a path parameter. status=open and limit=10 are query parameters. They look similar, but they do different jobs, and mixing them up is one of the most common reasons a request returns the wrong thing or nothing at all.

Path parameters identify which thing

A path parameter is part of the address itself. It tells the API exactly which record you mean.

GET /customers/42
GET /orders/A-1007
GET /customers/42/orders

API documentation usually shows path parameters as a placeholder in the URL, written as {id} or :id:

GET /customers/{customerId}

Path parameters are almost always required. Without one, you're asking for a different endpoint altogether: /customers is the list of all customers, not customer 42.

Query parameters describe how you want it

Query parameters come after a ? and are written as name=value pairs, separated by &:

GET /customers?country=ZA&status=active&page=2

They usually filter, sort or page through results, or switch an option on:

Query parameters are usually optional. Leave them out and the API falls back to a default, like returning the first page of everything.

Note

The order of query parameters doesn't matter: ?a=1&b=2 and ?b=2&a=1 mean the same thing. The order of path segments does: /customers/42/orders and /orders/42/customers are completely different requests.

A simple way to tell them apart

Ask yourself: "If I removed this value, would I be asking for a different thing, or the same thing in a different way?"

• Remove 42 from /customers/42 → you're asking for all customers. Different thing: path parameter.
• Remove status=open from /orders?status=open → you still get orders, just unfiltered. Same thing, different view: query parameter.

Setting both in Postman

You can type parameters straight into the URL bar, but Postman's Params tab is easier to read and harder to get wrong.

Query parameters

1. Enter the base URL: {{baseUrl}}/customers
2. Open the Params tab.
3. Under Query Params, add a row for each parameter: country = ZA, status = active.

Postman adds ?country=ZA&status=active to the URL for you. Untick a row's checkbox to switch it off without deleting it, which is handy when you're comparing filtered and unfiltered results.

Path parameters

Write the placeholder with a colon in the URL:

{{baseUrl}}/customers/:customerId

Postman adds a Path Variables table under the Params tab, where you fill in customerId = 42. Your saved request keeps the placeholder, so testing a different customer means changing one value.

Special characters need encoding

Some characters have special meanings in a URL. Spaces, &, ?, # and + all need to be URL-encoded when they appear inside a value:

So searching for "Smith & Sons" looks like this:

GET /customers?name=Smith%20%26%20Sons

Without encoding, the API reads & as the start of a new parameter and searches for "Smith " instead.

Tip

In Postman, select a value in the URL bar or the Params table, right-click, and choose EncodeURIComponent to encode it.

What to test

When a story adds or changes an endpoint with parameters, these checks catch most problems:

• Unknown path value. /customers/999999 should return 404, not 500 and not an empty 200.
• Badly formed path value. /customers/abc when IDs are numbers should return 400 or 404.
• Missing query parameters. Does the default behaviour match the acceptance criteria?
• Invalid query values. ?limit=-5 or ?status=banana should be rejected clearly or ignored safely.
• Combinations. Do two filters together narrow the results the way you'd expect?
• Special characters. Try a value with a space or an &.

The free exercise has you build exactly this kind of request: a GET with the right path and query parameters, with feedback on each part you get right or wrong.