Header Parameters

Learn how to work with HTTP headers in moclojer. Access and use request headers in dynamic responses (Authorization, User-Agent, etc).

HTTP headers carry metadata about the request and response. In moclojer, you can access headers sent by the client and use them in dynamic responses, as well as define custom headers in responses.

What Are HTTP Headers?

Headers are key-value pairs sent in HTTP requests and responses:

GET /api/users HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Authorization: Bearer token123
User-Agent: curl/7.64.1
Accept: application/json

Divided into:

Request Headers: Client → Server
Response Headers: Server → Client

Why Use Headers?

✅ Authentication: Authorization: Bearer token ✅ Content Negotiation: Accept: application/json ✅ Caching: Cache-Control, ETag ✅ CORS: Access-Control-Allow-Origin ✅ Tracking: X-Request-ID, X-Correlation-ID ✅ Client Info: User-Agent, Referer

Accessing Request Headers

Syntax: `{{header-params.HeaderName}}`

- endpoint:
    method: GET
    path: /api/protected
    response:
      status: 200
      body: >
        {
          "authenticated": true,
          "token": "{{header-params.Authorization}}",
          "userAgent": "{{header-params.User-Agent}}",
          "requestId": "{{header-params.X-Request-ID}}"
        }

Test:

curl http://localhost:8000/api/protected \
  -H "Authorization: Bearer abc123" \
  -H "User-Agent: MyApp/1.0" \
  -H "X-Request-ID: req-456"

Response:

{
  "authenticated": true,
  "token": "Bearer abc123",
  "userAgent": "MyApp/1.0",
  "requestId": "req-456"
}

Common Headers

1. Authorization (Authentication)

- endpoint:
    method: GET
    path: /api/me
    response:
      status: 200
      body: >
        {
          "userId": 1,
          "name": "John Doe",
          "authenticatedWith": "{{header-params.Authorization}}",
          "role": "admin"
        }

Request:

curl http://localhost:8000/api/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

{
  "userId": 1,
  "name": "John Doe",
  "authenticatedWith": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "role": "admin"
}

2. User-Agent (Client)

- endpoint:
    method: GET
    path: /api/analytics/track
    response:
      status: 200
      body: >
        {
          "tracked": true,
          "client": "{{header-params.User-Agent}}",
          "timestamp": "2024-01-15T10:00:00Z"
        }

Request:

curl http://localhost:8000/api/analytics/track \
  -H "User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)"

3. Content-Type

- endpoint:
    method: POST
    path: /api/data
    response:
      status: 200
      body: >
        {
          "receivedContentType": "{{header-params.Content-Type}}",
          "processed": true
        }

Request:

curl -X POST http://localhost:8000/api/data \
  -H "Content-Type: application/json" \
  -d '{"data": "test"}'

4. Accept (Content Negotiation)

- endpoint:
    method: GET
    path: /api/users
    response:
      status: 200
      headers:
        Content-Type: "{{header-params.Accept}}"
      body: >
        {
          "users": [],
          "format": "{{header-params.Accept}}"
        }

Request JSON:

curl http://localhost:8000/api/users \
  -H "Accept: application/json"

Request XML (simulated):

curl http://localhost:8000/api/users \
  -H "Accept: application/xml"

5. Custom Headers (X-*)

- endpoint:
    method: GET
    path: /api/service
    response:
      status: 200
      body: >
        {
          "requestId": "{{header-params.X-Request-ID}}",
          "correlationId": "{{header-params.X-Correlation-ID}}",
          "tenantId": "{{header-params.X-Tenant-ID}}",
          "apiVersion": "{{header-params.X-API-Version}}"
        }

Request:

curl http://localhost:8000/api/service \
  -H "X-Request-ID: req-123" \
  -H "X-Correlation-ID: corr-456" \
  -H "X-Tenant-ID: tenant-789" \
  -H "X-API-Version: v2"

Defining Response Headers

Simple Headers

- endpoint:
    method: GET
    path: /api/data
    response:
      status: 200
      headers:
        Content-Type: application/json
        X-Custom-Header: custom-value
        X-Rate-Limit: "100"
      body: >
        {"data": []}

Test:

curl -I http://localhost:8000/api/data

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json
X-Custom-Header: custom-value
X-Rate-Limit: 100

Dynamic Headers

- endpoint:
    method: GET
    path: /api/echo
    response:
      status: 200
      headers:
        Content-Type: application/json
        X-Echo-User-Agent: "{{header-params.User-Agent}}"
        X-Echo-Auth: "{{header-params.Authorization}}"
      body: >
        {
          "message": "Headers echoed"
        }

Request:

curl http://localhost:8000/api/echo \
  -H "User-Agent: MyClient/1.0" \
  -H "Authorization: Bearer token123"

Response headers include:

X-Echo-User-Agent: MyClient/1.0
X-Echo-Auth: Bearer token123

CORS Headers

- endpoint:
    method: GET
    path: /api/public
    response:
      status: 200
      headers:
        Content-Type: application/json
        Access-Control-Allow-Origin: "*"
        Access-Control-Allow-Methods: "GET, POST, PUT, DELETE, OPTIONS"
        Access-Control-Allow-Headers: "Content-Type, Authorization"
      body: >
        {"message": "CORS enabled"}

Or use global flag:

moclojer --config mocks.yml --enable-cors

Cache Headers

- endpoint:
    method: GET
    path: /api/static-data
    response:
      status: 200
      headers:
        Content-Type: application/json
        Cache-Control: "public, max-age=3600"
        ETag: '"abc123"'
        Last-Modified: "Mon, 15 Jan 2024 10:00:00 GMT"
      body: >
        {"data": "cacheable"}

Practical Use Cases

1. Bearer Token Authentication

# Protected endpoint - requires token
- endpoint:
    method: GET
    path: /api/protected
    response:
      status: 200
      headers:
        Content-Type: application/json
      body: >
        {
          "message": "Access granted",
          "user": {
            "id": 1,
            "tokenHash": "{{header-params.Authorization}}"
          }
        }

# Endpoint without token - returns 401
- endpoint:
    method: GET
    path: /api/protected
    response:
      status: 401
      headers:
        Content-Type: application/json
        WWW-Authenticate: 'Bearer realm="API"'
      body: >
        {
          "error": "Unauthorized",
          "message": "Bearer token is required"
        }

⚠️ Note: moclojer doesn't validate tokens. Both endpoints will respond. Use correct order or validation tools.

2. API Versioning via Header

- endpoint:
    method: GET
    path: /api/users
    response:
      status: 200
      headers:
        Content-Type: application/json
        X-API-Version: "{{header-params.X-API-Version}}"
      body: >
        {
          "version": "{{header-params.X-API-Version}}",
          "users": [
            {"id": 1, "name": "Alice"}
          ]
        }

Request v1:

curl http://localhost:8000/api/users \
  -H "X-API-Version: v1"

Request v2:

curl http://localhost:8000/api/users \
  -H "X-API-Version: v2"

3. Request Tracking

- endpoint:
    method: POST
    path: /api/events
    response:
      status: 202
      headers:
        Content-Type: application/json
        X-Request-ID: "{{header-params.X-Request-ID}}"
        X-Correlation-ID: "{{header-params.X-Correlation-ID}}"
      body: >
        {
          "eventId": "evt-123",
          "requestId": "{{header-params.X-Request-ID}}",
          "correlationId": "{{header-params.X-Correlation-ID}}",
          "status": "accepted"
        }

Request:

curl -X POST http://localhost:8000/api/events \
  -H "X-Request-ID: req-abc-123" \
  -H "X-Correlation-ID: corr-xyz-456" \
  -d '{"event": "user.signup"}'

4. Multi-Tenant API

- endpoint:
    method: GET
    path: /api/data
    response:
      status: 200
      headers:
        Content-Type: application/json
        X-Tenant-ID: "{{header-params.X-Tenant-ID}}"
      body: >
        {
          "tenantId": "{{header-params.X-Tenant-ID}}",
          "data": [
            {"id": 1, "value": "Data for tenant {{header-params.X-Tenant-ID}}"}
          ]
        }

Request:

curl http://localhost:8000/api/data \
  -H "X-Tenant-ID: tenant-acme-corp"

5. Rate Limiting Headers

- endpoint:
    method: GET
    path: /api/search
    response:
      status: 200
      headers:
        Content-Type: application/json
        X-RateLimit-Limit: "100"
        X-RateLimit-Remaining: "95"
        X-RateLimit-Reset: "1610712000"
      body: >
        {
          "results": []
        }

6. Content Negotiation

# JSON Response
- endpoint:
    method: GET
    path: /api/users
    response:
      status: 200
      headers:
        Content-Type: "{{header-params.Accept}}"
      body: >
        {
          "format": "{{header-params.Accept}}",
          "users": [{"id": 1, "name": "Alice"}]
        }

Request:

curl http://localhost:8000/api/users \
  -H "Accept: application/json"

curl http://localhost:8000/api/users \
  -H "Accept: application/xml"

Combining Parameters

Headers + Path + Query + Body

- endpoint:
    method: POST
    path: /api/tenants/:tenantId/users
    response:
      status: 201
      headers:
        Content-Type: application/json
        X-Tenant-ID: "{{header-params.X-Tenant-ID}}"
        X-Request-ID: "{{header-params.X-Request-ID}}"
        Location: "/api/tenants/{{path-params.tenantId}}/users/1"
      body: >
        {
          "id": 1,
          "tenantId": "{{path-params.tenantId}}",
          "name": "{{json-params.name}}",
          "email": "{{json-params.email}}",
          "role": "{{query-params.role}}",
          "requestId": "{{header-params.X-Request-ID}}",
          "createdAt": "2024-01-15T10:00:00Z"
        }

Request:

curl -X POST "http://localhost:8000/api/tenants/acme/users?role=admin" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: acme" \
  -H "X-Request-ID: req-123" \
  -d '{
    "name": "Alice",
    "email": "[email protected]"
  }'

Headers Case-Insensitive

HTTP headers are case-insensitive:

# All work:
{{header-params.Authorization}}
{{header-params.authorization}}
{{header-params.AUTHORIZATION}}

But convention:

Use Title-Case in headers: Content-Type, Authorization
Use exactly as defined in template

Standard Headers vs Custom

Standard Headers (Avoid X- prefix)

RFC 6648 discourages X- in new headers:

# ❌ Outdated
X-Request-ID: abc123

# ✅ Modern
Request-ID: abc123

But X- is still very common in practice:

X-Request-ID
X-Correlation-ID
X-API-Key
X-Forwarded-For

Custom Headers (Use specific prefix)

# ✅ Good (identifiable)
X-MyApp-Version: 1.0
X-MyApp-Client-ID: client-123

# ❌ Too generic
X-Version: 1.0

Best Practices

✅ Do

Use headers for metadata, not data

# ✅ Metadata
headers:
  Authorization: Bearer token

# ❌ Data should go in body
headers:
  X-User-Name: Alice
  X-User-Email: [email protected]

CORS headers when needed

headers:
  Access-Control-Allow-Origin: "*"
  Access-Control-Allow-Methods: "GET, POST"

Content-Type always explicit

headers:
  Content-Type: application/json

Request tracking headers

headers:
  X-Request-ID: "{{header-params.X-Request-ID}}"

❌ Avoid

Sensitive headers in logs

# ⚠️ Tokens appear in logs
"token": "{{header-params.Authorization}}"

Giant headers

# ❌ Headers have size limit (~8KB)
X-Large-Data: "..." (100KB)

Complex data in headers

# ❌ Use body for this
X-User-Data: '{"name":"Alice","email":"[email protected]"}'

Troubleshooting

Problem: Header is not replaced

Cause: Incorrect name (case-sensitive in template)

# Request: Authorization: Bearer token

# ❌ Doesn't work
{{header-params.authorization}}

# ✅ Works
{{header-params.Authorization}}

Problem: Custom header doesn't appear

Cause: Not defined in response

# ✅ Define explicitly
response:
  headers:
    X-Custom: "value"

Problem: CORS error

Solution:

# Enable CORS globally
moclojer --enable-cors

# Or per endpoint
headers:
  Access-Control-Allow-Origin: "*"

Important Headers

Header

Usage

Example

Authorization

Authentication

Bearer token123

Content-Type

Body type

application/json

Accept

Desired format

application/json

User-Agent

Client info

curl/7.64.1

X-Request-ID

Request tracking

req-abc-123

X-API-Key

API key auth

sk_live_abc123

Cache-Control

Caching policy

max-age=3600

Location

Redirect/Created

/users/123

Next Steps

Path Parameters - URL parameters
Query Parameters - Filters and pagination
Body Parameters - Data in body
HTTP Methods - GET, POST, etc.

hashtagWhat Are HTTP Headers?

hashtagWhy Use Headers?

hashtagAccessing Request Headers

hashtagSyntax: {{header-params.HeaderName}}

hashtagCommon Headers

hashtag1. Authorization (Authentication)

hashtag2. User-Agent (Client)

hashtag3. Content-Type

hashtag4. Accept (Content Negotiation)

hashtag5. Custom Headers (X-*)

hashtagDefining Response Headers

hashtagSimple Headers

hashtagDynamic Headers

hashtagCORS Headers

hashtagCache Headers

hashtagPractical Use Cases

hashtag1. Bearer Token Authentication

hashtag2. API Versioning via Header

hashtag3. Request Tracking

hashtag4. Multi-Tenant API

hashtag5. Rate Limiting Headers

hashtag6. Content Negotiation

hashtagCombining Parameters

hashtagHeaders + Path + Query + Body

hashtagHeaders Case-Insensitive

hashtagStandard Headers vs Custom

hashtagStandard Headers (Avoid X- prefix)

hashtagCustom Headers (Use specific prefix)

hashtagBest Practices

hashtag✅ Do

hashtag❌ Avoid

hashtagTroubleshooting

hashtagProblem: Header is not replaced

hashtagProblem: Custom header doesn't appear

hashtagProblem: CORS error

hashtagImportant Headers

hashtagNext Steps

hashtagSee Also

What Are HTTP Headers?

Why Use Headers?

Accessing Request Headers

Syntax: `{{header-params.HeaderName}}`

Common Headers

1. Authorization (Authentication)

2. User-Agent (Client)

3. Content-Type

4. Accept (Content Negotiation)

5. Custom Headers (X-*)

Defining Response Headers

Simple Headers

Dynamic Headers

CORS Headers

Cache Headers

Practical Use Cases

1. Bearer Token Authentication

2. API Versioning via Header

3. Request Tracking

4. Multi-Tenant API

5. Rate Limiting Headers

6. Content Negotiation

Combining Parameters

Headers + Path + Query + Body

Headers Case-Insensitive

Standard Headers vs Custom

Standard Headers (Avoid X- prefix)

Custom Headers (Use specific prefix)

Best Practices

✅ Do

❌ Avoid

Troubleshooting

Problem: Header is not replaced

Problem: Custom header doesn't appear

Problem: CORS error

Important Headers

Next Steps

See Also