Structuring Request Payloads
| Header | Purpose |
|---|
Content-Type | Format of request body |
Accept | Desired response format |
Authorization | Credentials |
Content-Length | Body size in bytes |
User-Agent | Client identifier |
Accept-Encoding | Supported compression (gzip, br) |
Accept-Language | Preferred locale |
If-Match / If-None-Match | Conditional requests |
Idempotency-Key | Safe retry key for POST |
2. Structuring Request Body
| Method | Body Convention |
|---|
| POST (create) | Resource representation without server-generated fields (id, createdAt) |
| PUT (replace) | Complete resource representation |
| PATCH (partial) | Only fields to change (Merge Patch) or operations array (JSON Patch) |
| DELETE | Usually empty |
Example: Well-Structured POST Body
{
"name": "Alice Smith",
"email": "alice@example.com",
"preferences": {
"newsletter": true,
"locale": "en-US"
},
"tags": ["beta-tester", "premium"]
}
3. Using Query Parameters
| Pattern | Example |
|---|
| Single value | ?status=active |
| Multi-value (repeat) | ?tag=red&tag=blue |
| Multi-value (CSV) | ?tags=red,blue,green |
| Range | ?createdAt[gte]=2026-01-01 |
| Sort | ?sort=-createdAt,name |
4. Using Path Parameters
| Use For | Example |
|---|
| Identifying resource | /users/{userId} |
| Hierarchy traversal | /users/{userId}/orders/{orderId} |
| Required fields only | Optional → use query string |
5. Using Request Body for Complex Data
| Scenario | Why Body |
|---|
| Nested objects, arrays | Query strings flatten poorly |
| Large payloads (> 2KB) | URL length limits (~2048 chars) |
| Sensitive data | URLs logged; bodies usually not |
| Binary data | Cannot be represented in URL |
Note: Avoid GET with body — many proxies strip it. For complex queries, use POST /searches with query body.
| Content-Type | Format | Use |
|---|
application/x-www-form-urlencoded | name=Alice&email=a%40x.com | Simple HTML forms |
multipart/form-data | Boundary-separated parts | File uploads, mixed fields |
7. Handling Multipart Requests
Example: Multipart Upload
POST /api/avatars HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
------WebKitFormBoundary
Content-Disposition: form-data; name="userId"
42
------WebKitFormBoundary
Content-Disposition: form-data; name="avatar"; filename="me.png"
Content-Type: image/png
<binary data>
------WebKitFormBoundary--
| Part Header | Purpose |
|---|
Content-Disposition | Field name + optional filename |
Content-Type | Per-part MIME type |
8. Validating Request Data
| Layer | Validation |
|---|
| Schema | Required fields, types, formats (JSON Schema, OpenAPI) |
| Business | Cross-field rules, uniqueness, state transitions |
| Security | Sanitization (XSS), injection prevention |
| Authorization | Field-level permission checks |
9. Handling Request Size Limits
| Limit Type | Typical Value |
|---|
| URL length | 2048 chars (varies by browser/server) |
| JSON body | 1-10 MB (express default 100KB) |
| Multipart upload | 10-100 MB (configurable) |
| Streaming upload | Unlimited (chunked) |
Warning: Set explicit limits to prevent DoS via huge payloads. Return 413 Payload Too Large.
| Header | Use Case |
|---|
X-Request-ID | Trace requests across services |
X-Tenant-ID | Multi-tenant routing |
Idempotency-Key | Safe POST retries |
X-Client-Version | Client app version for analytics |