API Parameters Explained: Path, Query, Header & Body (2026)

API Parameters Explained: Path, Query, Header & Body

Every API request you make carries information to the server through parameters. Whether you are fetching user data, filtering search results, or submitting a form, parameters are how your client tells the server what to do. Understanding the four main parameter types, when to use each one, and how they work together is fundamental to working with any REST API.

This guide breaks down every parameter type with real-world examples, comparison tables, and best practices you can apply immediately.

The Four Types of API Parameters

Parameter Type	Location	Purpose	Example
Path	URL path	Identify a specific resource	/users/42
Query	After ? in URL	Filter, sort, paginate	?status=active&page=2
Header	HTTP headers	Auth, content type, metadata	Authorization: Bearer token
Body	Request body	Send data payloads	{"name": "Alice"}

Each type serves a distinct purpose. Mixing them up leads to confusing APIs, security issues, and debugging headaches. Let's go through each one in detail.

Path Parameters

Path parameters are embedded directly in the URL path. They identify a specific resource or a nested resource within a collection.

Syntax

Path parameters appear as dynamic segments in the URL, typically wrapped in curly braces in API documentation:

GET /api/v1/users/{userId}
GET /api/v1/users/{userId}/orders/{orderId}

Real Example

# Get user with ID 42
curl https://api.example.com/v1/users/42

# Get order 789 belonging to user 42
curl https://api.example.com/v1/users/42/orders/789

When to Use Path Parameters

• To identify a specific resource (a user, a product, an order)
• To express hierarchical relationships (a comment on a post)
• When the parameter is required for the endpoint to make sense

Common Mistakes

• Using path parameters for optional values (use query parameters instead)
• Putting sensitive data in the URL path (it gets logged in server logs and browser history)
• Deeply nesting more than 2-3 levels (/a/{id}/b/{id}/c/{id}/d/{id} is too deep)

Query Parameters

Query parameters appear after the ? in a URL and are separated by &. They are used for filtering, sorting, pagination, and other optional modifiers.

Syntax

GET /api/v1/products?category=electronics&sort=price&order=asc&page=1&limit=20

Real Example

# Search for active users in the "engineering" department, page 2
curl "https://api.example.com/v1/users?status=active&department=engineering&page=2&limit=25"

# Filter products by price range
curl "https://api.example.com/v1/products?min_price=10&max_price=100&in_stock=true"

Common Query Parameter Patterns

Pattern	Example	Purpose
Pagination	?page=2&limit=20	Navigate through large datasets
Filtering	?status=active&role=admin	Narrow results
Sorting	?sort=created_at&order=desc	Control result order
Searching	?q=search+term	Full-text search
Field selection	?fields=id,name,email	Reduce response size
Expansion	?expand=orders,profile	Include related resources

When to Use Query Parameters

• For optional parameters that modify how data is returned
• For filtering, sorting, and pagination
• For search queries
• When the endpoint works without the parameter (sensible defaults exist)

Best Practices

# Good: Descriptive parameter names with sensible defaults
GET /api/v1/orders?status=pending&sort=created_at&order=desc&page=1&per_page=20

# Bad: Cryptic single-letter names
GET /api/v1/orders?s=p&o=c&d=d&p=1&n=20

Header Parameters

Header parameters are key-value pairs sent in the HTTP request headers. They carry metadata about the request itself rather than business data.

Syntax

GET /api/v1/users HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

Real Example

# Authenticated request with content negotiation
curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "X-API-Version: 2026-01-01"

Standard vs Custom Headers

Header	Type	Purpose
Authorization	Standard	Authentication credentials
Content-Type	Standard	Format of the request body
Accept	Standard	Desired response format
Cache-Control	Standard	Caching directives
X-Request-ID	Custom	Request tracing
X-API-Version	Custom	API version selection
X-Rate-Limit-Remaining	Custom	Rate limit info (response)

When to Use Header Parameters

• Authentication (API keys, bearer tokens, OAuth)
• Content negotiation (Accept, Content-Type)
• Request metadata (tracing IDs, client version)
• API versioning (some APIs use headers instead of URL paths)

Security Note

Headers are the correct place for sensitive authentication data. Unlike path and query parameters, headers are not stored in browser history, server access logs (by default), or referrer headers when navigating to other pages.

# Good: API key in header
curl -H "Authorization: Bearer sk-abc123" https://api.example.com/data

# Bad: API key in query string (gets logged everywhere)
curl "https://api.example.com/data?api_key=sk-abc123"

Body Parameters

Body parameters carry the main data payload in POST, PUT, and PATCH requests. The body can be formatted as JSON, form data, XML, or binary data depending on the API.

JSON Body (Most Common)

curl -X POST https://api.example.com/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "engineer",
    "department": "platform",
    "preferences": {
      "theme": "dark",
      "notifications": true
    }
  }'

Form Data Body

# URL-encoded form data
curl -X POST https://api.example.com/v1/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=alice&password=secret123"

# Multipart form data (file upload)
curl -X POST https://api.example.com/v1/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@photo.jpg" \
  -F "description=Profile photo"

Body Content Types

Content-Type	Format	Use Case
application/json	JSON	Most API data exchange
application/x-www-form-urlencoded	Key-value pairs	Simple form submissions
multipart/form-data	Mixed content	File uploads
application/xml	XML	Legacy/enterprise APIs
application/octet-stream	Raw binary	Binary file transfer

When to Use Body Parameters

• Creating new resources (POST)
• Updating existing resources (PUT, PATCH)
• Sending complex or nested data structures
• File uploads

Important Rules

1. GET and DELETE requests should not have a body (some servers ignore it)
2. Always set the Content-Type header to match your body format
3. Validate body data on both client and server side
4. Use PATCH for partial updates and PUT for full replacements

Putting It All Together

Here is a real-world example that uses all four parameter types in a single request:

# Update a specific user's profile picture
# - Path parameter: userId (42)
# - Query parameter: overwrite (true)
# - Header parameters: Authorization, Content-Type
# - Body parameter: the image file

curl -X PUT "https://api.example.com/v1/users/42/avatar?overwrite=true" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: multipart/form-data" \
  -F "avatar=@new-profile.jpg"

Decision Matrix

Use this table to decide which parameter type to use:

Question	Answer	Use
Does it identify a specific resource?	Yes	Path parameter
Is it optional/for filtering?	Yes	Query parameter
Is it metadata about the request?	Yes	Header parameter
Is it authentication data?	Yes	Header parameter
Is it a data payload for create/update?	Yes	Body parameter
Is it a file?	Yes	Body parameter (multipart)

Common Pitfalls and How to Avoid Them

1. Putting sensitive data in URLs. API keys, tokens, and passwords should go in headers, never in path or query parameters.

2. Overloading query strings. If your query string has 15 parameters, consider using a POST request with a JSON body instead.

3. Ignoring Content-Type. Mismatched Content-Type headers cause cryptic 400 or 415 errors. Always match the header to the actual body format.

4. Not URL-encoding query parameters. Special characters in query values must be encoded: spaces become %20 or +, & becomes %26.

# Bad: unencoded space breaks the URL
curl "https://api.example.com/search?q=hello world"

# Good: properly encoded
curl "https://api.example.com/search?q=hello%20world"

5. Sending a body with GET requests. While technically possible, many servers, proxies, and clients will strip or ignore it. Use query parameters for GET requests.

Testing Your API Parameters

The fastest way to test API parameters is with a tool like curl or an API client. If you are building applications that interact with AI media generation APIs, Hypereal AI provides well-documented endpoints with clear parameter specifications for image, video, and audio generation, making it straightforward to get started without guesswork.

Summary

Understanding the four API parameter types is essential for every developer:

• Path parameters identify specific resources in the URL
• Query parameters filter, sort, and paginate results
• Header parameters carry authentication and metadata
• Body parameters send data payloads for creating or updating resources

Choose the right parameter type for each piece of data, follow the conventions of the API you are working with, and always keep sensitive information out of URLs.