Glossary

HTTP header

HTTP headers supplement the message body with instructions about how to interpret it, who may use the response and how the request should be processed. A value sent by the client is not inherently trustworthy.

Short definition

Named metadata alongside the URL and message body.

Both an HTTP request and response can contain a set of header fields. Each has a name and value; HTTP header names are case-insensitive. In HTTP/1.1, headers sit between the start line and the blank line that separates the optional message body. HTTP/2 and HTTP/3 transport them differently, but their meaning remains part of HTTP semantics.

A header is not a universal container for arbitrary data. Its name and meaning are defined by a standard, documented contract or deliberately designed extension. Content-Type commonly says whether the body is JSON, Accept states a preferred representation, Authorization carries authentication credentials and Cache-Control defines caching rules.

What it is used for

Describing messages, controlling caches and forwarding security context

The same JSON can have a different meaning depending on the method, URI and relevant headers.

Content-Type and Accept for the type and negotiation of a data representation
Authorization, WWW-Authenticate and cookies for sign-in and API access
Cache-Control, ETag and Last-Modified for storage and conditional retrieval of a response
Content-Security-Policy, Strict-Transport-Security and Set-Cookie for browser security
X-Request-ID, traceparent and, in a controlled manner, Forwarded for tracing a request through proxies

Practical example

A webhook with a content type, signature and tracing

A carrier sends a webhook about a shipment status change. Content-Type tells the application to process JSON safely, the signature header is used to verify integrity according to the agreed procedure, and X-Request-ID helps trace the specific delivery. The application verifies the signature over the precisely defined data; the header name alone is not proof of origin.

Response 204 says that the server accepted the event without returning a body. If processing is asynchronous, 204 is not a claim that the shipment has already been propagated to every downstream system.

POST /webhooks/carrier HTTP/1.1
Content-Type: application/json
X-Signature: sha256=<podpis>
X-Request-ID: 01H...

{"shipmentId":"S-42","status":"delivered"}

HTTP/1.1 204 No Content
X-Request-ID: 01H...
Cache-Control: no-store

How it works

A header gains meaning only for the correct recipient

A recipient evaluates only the fields it understands and that are trustworthy at that point in the path.

The client builds a request It adds Accept, Content-Type and Authorization, for example. Depending on the situation, a browser also sends cookies or an origin.
The proxy applies its own rules A reverse proxy can set, remove or add fields. Forwarded headers received from the internet must not be passed off as trusted context without processing.
The application validates the contract It checks the expected Content-Type, verifies the token and determines whether a specific custom header belongs to the documented API version.
The response describes the result The server returns a status, Content-Type, caching rules and optional security or diagnostic fields.
The client or cache interprets them The browser applies the security policy, the client selects a JSON parser and the cache decides whether to store or revalidate the response according to the rules.

Main parts and concepts

Not every header behaves the same way along the entire path.

Distinguishing purpose and trustworthiness helps prevent errors in both APIs and proxy configurations.

Request and response fields

Accept or Authorization belongs in a request. Content-Type, Cache-Control or Location often describes a response. Some fields can exist on both sides, but their meaning differs.

Content representation

Content-Type identifies the media type of the body, such as application/json. Accept states what the client can receive; it does not command the server to produce any requested format.

End-to-end and hop-by-hop

End-to-end fields are intended for the client and final server even across intermediaries. Hop-by-hop fields concern one connection, and a proxy does not forward them as application metadata. Connection is not a mechanism for carrying custom business context.

Authentication and sensitivity

Authorization or Cookie can contain sensitive information. They must not be written in full to ordinary logs or forwarded to another domain during a redirect. The presence of a header also does not mean the token is valid.

Custom and forwarded headers

A custom field needs a stable name and documentation; the historic X- prefix makes it neither secure nor standard. X-Forwarded-For or Forwarded can be trusted only from a controlled proxy chain.

Benefits and limitations

Standard metadata provides interoperability but requires precise ownership.

Benefits

separation of metadata from the URL and response content itself
standard interoperability among clients, caches, browsers, proxies and API gateways
the ability to control content type, caching, security policy and request traceability
an extensible contract without changing the shape of every JSON payload

Limitations and common mistakes

trusting an IP address, scheme or user solely from a client-supplied header
sending a token or cookie to a log, analytics system or external redirect
a mismatch between Content-Type and the actual body
using a custom field without documentation, validation and versioning
treating a CORS or CSP header as server-side authorization

When it makes sense

When the information belongs to the message rather than the internal logic of the URL.

Headers are suitable for standard HTTP metadata such as the content type, preferred representation, caching, authentication or tracing. In an integration API, an idempotency key can belong in a header when the contract defines it that way; a custom business value such as an item price usually belongs in the validated request body.

Adding a new header is not a substitute for design. The contract must define whether the client may send it, whether a proxy forwards it, how it is validated, whether it can be repeated and whether it may be logged. For sensitive or security-related values, the source the application trusts matters more than the field name.

What to consider

Every field should have a meaning, source and safe handling procedure.

An interface is clearer when it uses standard headers and keeps custom extensions to a minimum.

set and validate Content-Type for requests with a body and responses containing data
mask Authorization, Cookie and other secrets in both application and proxy logs
trust Forwarded or X-Forwarded-* only from known proxy addresses
document custom fields, their length limits and behaviour when a value is missing
test security and caching headers in HTTP integration tests

Common questions

HTTP headers in practice

Are HTTP header names case-sensitive?

No. HTTP field names are compared case-insensitively. In HTTP/2 and HTTP/3, they are commonly displayed in lowercase.

Is Content-Type the same as Accept?

No. Content-Type describes the actual message body. Accept states which representations the client prefers or can receive.

Can a backend trust X-Forwarded-For?

Only if the request arrived through a known proxy that replaced or correctly processed the client-supplied value. A direct client can forge it freely.

Should I log Authorization for debugging?

Not in its normal form. A token or cookie is sensitive; diagnostics should use masking, request IDs and other non-invasive metadata.

How I work with APIs in practice

I keep HTTP contracts readable across proxies and integration boundaries.

When developing APIs, I address headers, authentication, webhook signatures, caching and tracing so clients and operations both know what happened to a request.

How I work with APIs and integrations Discuss your project without obligation