Restful Headers

title: "RESTful Headers — Custom and Standard HTTP Headers in REST APIs" description: "RESTful HTTP headers carry metadata about requests and responses including content type, authentication, caching, pagination, and custom application headers." date: 2026-06-28 lastmod: 2026-06-28 weight: 13 tags: [apis, restful] }

RESTful HTTP headers communicate metadata between client and server: Content-Type for format negotiation, Authorization for credentials, and custom headers for application context.

What You'll Learn

• Standard request/response headers
• Custom application headers
• Header naming conventions

Why It Matters

Headers provide essential context that doesn't belong in the URI or body. Correct header usage improves API quality and interoperability.

Important Headers

Code Examples

from flask import request, jsonify
import uuid

@app.before_request
def add_request_id():
    request.request_id = request.headers.get('X-Request-Id', str(uuid.uuid4()))

@app.after_request
def add_response_headers(response):
    # Echo request ID back
    response.headers['X-Request-Id'] = getattr(request, 'request_id', '')

    # CORS headers
    response.headers['Access-Control-Allow-Origin'] = '*'
    response.headers['Access-Control-Allow-Methods'] = 'GET, POST, PUT, DELETE, PATCH'

    # Cache control
    if request.method == 'GET':
        response.headers['Cache-Control'] = 'public, max-age=60'

    return response

@app.route('/users', methods=['POST'])
def create_user():
    # Check content type
    if request.content_type != 'application/json':
        return jsonify({"error": "Expected application/json"}), 415

    # Process request
    user = db.create_user(request.json)

    response = jsonify(user.to_dict())
    response.status_code = 201
    response.headers['Location'] = f'/users/{user.id}'
    response.headers['X-Resource-Version'] = '1'
    return response

// Custom header middleware
app.use((req, res, next) => {
  req.requestId = req.headers['x-request-id'] || crypto.randomUUID();
  res.set('X-Request-Id', req.requestId);

  // Rate limit headers
  res.set('X-RateLimit-Limit', 100);
  res.set('X-RateLimit-Remaining', getRemaining(req));
  res.set('X-RateLimit-Reset', getResetTime());

  next();
});

app.post('/api/users', (req, res) => {
  const user = createUser(req.body);

  res.set('Location', `/api/users/${user.id}`);
  res.set('X-Resource-Version', '1');
  res.status(201).json(user);
});

Common Mistakes

1. Reinventing Standard Headers

Don't create X-Content-Type when Content-Type exists.

2. Not Echoing X-Request-Id

Request correlation requires round-trip request ID.

3. Missing CORS Headers

Client-side apps can't access your API without proper CORS.

4. No Rate Limit Headers

Clients need RateLimit headers to back off properly.

5. Case-Sensitive Header Parsing

HTTP headers are case-insensitive. Always normalize to lowercase.

Practice Questions

1. What header indicates the response format?
2. What header carries authentication credentials?
3. What header indicates created resource location?
4. What is X-Request-Id used for?
5. What CORS header allows cross-origin requests?

Answers:

1. Content-Type (response) and Accept (request).
2. Authorization.
3. Location.
4. Correlating requests across services for debugging.
5. Access-Control-Allow-Origin.

Challenge: Implement a consistent header strategy for your API. Add request ID, rate limit, CORS, and version headers to all responses.

FAQ