4 Ways to Send Data in an API Request
APIs are fundamentally about exchanging data between systems. The four main options are the request body, query parameters, headers, and path parameters (often just called route parameters). Deciding where to place that data in a request is important for keeping things straightforward and functional. Each has its own role, and choosing appropriately makes your API easier to understand and maintain. Misplace them, and it might cause issues for anyone working with it later.
1. Request Body
The request body is where you typically put the bulk of the data you're sending to the server. It's common in methods like POST, PUT, and PATCH, which are used for creating or updating resources.
Example:
text
POST /api/users
Content-Type: application/json
{
"name": "Kris",
"email": "kris@example.com"
}
Common use:
- Sending structured or complex data, such as JSON objects, arrays, or files in create or update operations.
When to use:
When you need to transmit detailed payloads that don't fit well in the URL.
It keeps sensitive information out of the URL, which isn't visible in logs or browser history.
Servers don't cache or log bodies by default, adding a layer of security.
When to avoid it:
- Don't use it with GET requests, as those are for retrieving data, not sending it. Some servers might even reject bodies in GETs.
2. Query Parameters
Query parameters go in the URL after a question mark (?). They're straightforward for adding extra details like filters or pagination.
Example:
text
GET /api/users?role=admin&page=2
Common use:
- Applying filters, handling pagination, or passing optional flags in read operations.
When to use:
They're easy to implement, test, and modify—just tweak the URL.
Great for optional values or small bits of information that refine a request.
When to avoid it:
Skip them for sensitive data like passwords or API keys, since URLs can be logged or shared.
Avoid them for large or nested data; URLs have length limits (around 2,000 characters in practice), and they can quickly become unreadable.
3. HTTP Headers
Headers provide metadata about the request itself, rather than the core data. They're commonly used for authentication, specifying formats, or other instructions.
Example:
text
GET /api/profile
Authorization: Bearer eyJhbGciOiJI...
Accept-Language: en-US
Common use:
- Handling authentication, content negotiation, or localization settings.
When to use:
They separate control information from the main payload, keeping things organized.
Essential for things like auth tokens, content types, or client preferences.
When to avoid it:
Don't stuff application-specific data into headers; that's not their purpose and can complicate things.
Stick to standard headers when possible—custom ones should only be added if they solve a specific problem.
4. Path Parameters
Path parameters are embedded right in the URL path, helping identify specific resources in a clean way. They align well with RESTful API designs.
Example:
text
GET /api/users/42
Common use:
- Specifying unique identifiers for resources in RESTful endpoints.
When to use:
It makes the endpoint clear and human-readable, showing exactly what resource is being targeted.
Perfect for required identifiers, like user IDs or product codes.
When to avoid it:
Not for optional filters or search criteria—use query parameters for those.
Keep them simple; too many can make routes hard to manage.
Choosing the Right Approach
Here's a quick reference table to help decide:
| Location | Common Use | Example |
| Body | Main payload for creates/updates | POST /api/users with JSON data |
| Query Params | Filters, pagination, options | /api/users?active=true |
| Headers | Auth, metadata, preferences | Authorization: Bearer ... |
| Path Params | Resource identifiers | /api/users/123 |
If you're unsure, consider the data's purpose:
Does it specify the exact resource? → Path parameter.
Is it an optional refinement? → Query parameter.
Is it the actual content being sent? → Body.
Does it provide instructions or context? → Header.
Final Notes
Well-designed APIs are straightforward and consistent, so developers (including future you) don't have to second-guess where things go. Sticking to these conventions not only makes your code cleaner but also simplifies documentation and integration with clients. If you're building or using an API, start with these basics and adjust based on your specific needs.
