REST API Headers, Query Parameters, and Path Parameters
An API request carries information in four places: the URL path, query parameters, headers, and the request body. Knowing which type of input goes where is a fundamental API design skill. Putting data in the wrong place leads to security issues, confusing APIs, and hard-to-use endpoints.
The Three Channels of Input (Besides the Body)
Full URL example:
https://api.shop.com/products/42?color=red&sort=price
─────┬───── ─────────────┬────────
│ │
Path Parameter Query Parameters
Plus request headers (not visible in URL):
Authorization: Bearer eyJhbGc...
Accept: application/json
Content-Type: application/json
Path Parameters: Identifying a Specific Resource
Path parameters appear directly inside the URL and identify a specific resource. They are part of the resource address itself.
Pattern: /products/{id}
Example: /products/42
──
└── Path parameter: id = 42
More examples:
/users/99/orders/7
─┬ ─
│ └── orderId = 7
└── userId = 99
Use path parameters when the value is required and uniquely identifies a resource. Without the path parameter, the endpoint would not make sense or would point to a different resource entirely.
✅ Use path parameters for: GET /articles/15 → specific article DELETE /comments/8 → specific comment to delete PUT /users/3/profile → profile of user 3 ❌ Do not put filters or optional things in the path: GET /products/electronics/cheap ← "cheap" is a filter, not an ID
Query Parameters: Modifying How Data Is Returned
Query parameters come after a ? in the URL. They are key-value pairs separated by &. They modify or filter the response without changing which resource you are asking for.
/products?category=electronics&sort=price&order=asc&page=2 Breakdown: category=electronics → filter by category sort=price → sort results by price order=asc → ascending order page=2 → get the second page of results
Common Uses for Query Parameters
Use Case │ Example
─────────────────┼───────────────────────────────────────────────────
Filtering │ /users?status=active
│ /orders?date=2024-06-01&status=shipped
Sorting │ /products?sort=price&order=desc
Pagination │ /articles?page=3&limit=10
Searching │ /products?search=wireless+keyboard
Field selection │ /users?fields=id,name,email
When to Use Path Parameters vs Query Parameters
┌─────────────────────────────────────┬────────────────────────────────┐
│ Path Parameters │ Query Parameters │
├─────────────────────────────────────┼────────────────────────────────┤
│ Required to identify the resource │ Optional modifiers │
│ The URL breaks without them │ URL still works without them │
│ Specific identity: /users/5 │ Filters: /users?role=admin │
│ Hierarchical: /users/5/orders/2 │ Sorting, pagination, search │
└─────────────────────────────────────┴────────────────────────────────┘
Decision diagram:
"Is this value needed to identify which resource I'm talking about?"
│
├── Yes → Path parameter: /books/17
│
└── No → Query parameter: /books?author=tolkien
HTTP Headers: Metadata About the Request
Headers carry metadata — information about the request or response itself, not about the business data. They travel separately from the URL and body.
Common Request Headers
Header │ Purpose │ Example ────────────────────┼───────────────────────────────┼────────────────────────────── Authorization │ Authentication token │ Bearer eyJhbGciOiJIUzI1N... Content-Type │ Format of the request body │ application/json Accept │ Format the client wants back │ application/json Accept-Language │ Preferred language │ en-IN Cache-Control │ Caching instructions │ no-cache X-Request-ID │ Unique ID for tracking │ a1b2-c3d4-e5f6
Common Response Headers
Header │ Purpose │ Example ─────────────────────┼───────────────────────────────┼──────────────────────────── Content-Type │ Format of the response body │ application/json Cache-Control │ How long to cache response │ max-age=3600 Location │ URL of newly created resource│ /products/88 X-RateLimit-Limit │ Max requests per hour │ 1000 X-RateLimit-Remaining│ Requests left this hour │ 842
The Content-Type and Accept Headers
These two headers control the format of data being exchanged.
Content-Type: tells the server what format you are SENDING
Accept: tells the server what format you want to RECEIVE
Request with JSON body:
POST /products
Content-Type: application/json ← I am sending JSON
Accept: application/json ← I want JSON back
{ "name": "Speaker", "price": 999 }
If the server cannot return the requested format:
415 Unsupported Media Type (wrong Content-Type)
406 Not Acceptable (server cannot return requested format)
Custom Headers
You can create your own headers for API-specific metadata. Prefix them with X- (though this prefix is no longer required by modern standards, it is still common and helps identify custom headers).
Custom headers your API might use: X-API-Key: sk_live_abc123 ← API key authentication X-Request-ID: req-7f2a8b ← track a specific request X-Tenant-ID: org_456 ← multi-tenant identifier X-API-Version: 2 ← version via header
What Not to Put in Headers
❌ Never put these in headers: Business logic parameters → use path or query params Large data payloads → use the request body Sensitive data in plain GET URL query strings → use body or headers
Key Points
- Path parameters identify a specific resource:
/products/42 - Query parameters filter, sort, or paginate without identifying a specific item:
/products?sort=price - Headers carry metadata — authentication, content type, caching
- Content-Type tells the server the format of what you are sending
- Accept tells the server the format you want to receive
- Do not put business data in headers; keep headers for transport-level metadata