Query vs Path vs Body Params

Three places, three jobs

A request can carry parameters in three distinct places, and each one has a clearly defined role. Path parameters identify which resource you mean. Query parameters refine how a collection is returned to you. Body parameters carry the actual data you are sending to be stored or acted upon. Putting each kind in its proper place is what makes a request readable and its behaviour predictable.

Getting this wrong is a frequent source of confusion for everyone who later reads the call. A filter wedged awkwardly into the path, or a record identifier buried inside the body, fights the conventions that every REST API quietly shares, and it makes your integration harder for the next person — or the next version of you — to understand at a glance.

Path parameters

Path parameters are part of the URL itself, and they pin down one specific resource. In /v1/cases/12345, the 12345 is a path parameter naming exactly one case and nothing else. They are required by their very nature — without them the address points nowhere meaningful — and they form part of the resource's stable identity.

GET /v1/customers/cus_88/invoices/inv_12

Read a path from left to right as a hierarchy that narrows as it goes: this particular customer, and then that particular invoice belonging to them. Path parameters always answer the same fundamental question — "which one?" — and they are how you address a single, definite thing rather than a list of candidates.

Query parameters

Query parameters follow the ? in the URL and shape a collection request rather than identifying a single resource. Filtering, sorting, pagination, and field selection all live here, and they are typically optional, each with a sensible default the server applies when you leave it out.

Because they are optional and freely combinable, query parameters are perfect for the many small adjustments a caller might want to make to a list — something like ?status=open&sort=-created_at&limit=50 chains three of them together cleanly. Where path parameters answer "which record?", query parameters answer a different question entirely: "how would you like this collection returned?" Keeping that distinction clear in your head makes building requests almost mechanical.

Body parameters

Body parameters carry the payload for methods that send data — chiefly POST, PUT, and PATCH. The body is usually a JSON document describing the resource you are creating or the precise changes you are making, and unlike a query string it can be richly structured with nested objects, arrays, and deeply typed values.

GET requests, by deliberate contrast, should not rely on a body at all; their inputs belong in the path and the query string, where caches and tools expect to find them. Keep create-and-update data in the body, where it can be as detailed and as nested as the operation genuinely requires, and leave the URL to do the work of addressing and refining.

A rule of thumb

The whole topic collapses into one memorable rule: identify with the path, refine with the query, and send with the body. And alongside it, one firm prohibition — never put secrets or credentials in the URL, since paths and query strings are routinely logged by servers, proxies, and browser history, where a leaked token can linger for a long time. Authentication belongs in headers instead, well away from anything that gets written to a log.

For a closer look at how query parameters in particular drive list endpoints, read filtering and sorting, which expands on the refinement half of this rule in practical detail.