Ongoing discussions within the SWIM Community of Interest
HTTP Headers and AMQP Properties
The SFG‑approved version of this material is published at https://swim-eurocontrol.atlassian.net/wiki/x/C4CeX .
This page contains working material and may differ from the approved version. Once SFG approves it, this content is used to update the page in the SWIM Supporting Material Confluence space.
- 1 Context and Rationale
- 2 Design Principles
- 3 Core Functional Areas and Properties
- 3.1 Distributed Tracing and Correlation (traceparent, tracestate)
- 3.2 Content Negotiation and Representation (Content-Type, Accept, Accept-Encoding, Content-Encoding)
- 3.3 Message Size and Streaming Behaviour (Content-Length, Transfer-Encoding)
- 3.4 Authentication and Authorization (Authorization)
- 3.5 Retry and Resilience (Retry-After)
- 3.6 Security Headers (OWASP Alignment)
- 3.7 Deprecated and Non-Recommended Headers
- 4 Alignment with AMQP Properties
- 5 Property Catalogue
- 6 Security Considerations (OWASP)
Context and Rationale
Within SWIM Services (e.g. those developed in the context of CP1), HTTP Request/Reply is widely used for service interactions such as subscription management, flight object retrieval, and MET APIs. However, current SWIM TI Yellow Profile documentation provides only limited guidance on HTTP properties, mainly focusing on Content-Type and Content-Encoding.
As a result, each service tends to define its own set of HTTP headers, leading to inconsistencies in areas such as:
security
caching
tracing
transport behaviour
This guidance aims to establish a common, standardised approach to technical HTTP headers which are related to the use of the communication protocol itself, such as content negotiation, security, caching and tracing. Additional business-related metadata (e.g. AMHS recipient information) may be augmented on a per-service basis and will be addressed in later versions as needs and use cases emerge. This guidance is grounded in:
IETF RFCs (HTTP semantics and behaviour)
OWASP recommendations (security best practices)
and aligned with existing AMQP property usage where relevant.
Design Principles
Prefer Standard Headers Over Custom Definitions
When designing service interfaces, there is often a temptation to introduce custom headers or domain-specific identifiers. While this may appear convenient in the short term, it creates fragmentation and limits interoperability.
Standard HTTP headers should therefore be preferred when they exist. For example, instead of introducing a custom correlation header, HTTP-based services should rely on the W3C Trace Context specification, which defines the traceparent header. This header carries a globally unique trace identifier and enables full integration with modern observability platforms.
Custom headers should therefore only be introduced where:
no standard equivalent exists, and
the semantics are clearly defined and agreed across services.
This approach ensures that services remain compatible with standard tooling (e.g. gateways, monitoring platforms) and avoids the proliferation of slightly different but overlapping concepts.
Core Functional Areas and Properties
Distributed Tracing and Correlation (traceparent, tracestate)
To support end-to-end traceability, HTTP services should support propagation of trace context in accordance with the W3C Trace Context specification.
This is achieved including the traceparentheader in the service requests. This header carries a trace identifier that uniquely represents a transaction across service interactions.
A service should use a valid incoming traceparent header to continue an existing trace and include the appropriate trace context when making downstream calls. If no valid traceparent is received, the request should still be processed normally and the service may start a new trace.
In practice, when processing a request, a participating service should:
extract and validate
traceparent, when present;continue the incoming trace, or start a new trace when no valid trace context is available; and
include an updated
traceparentin downstream requests so that the resulting operations remain connected within the same trace.
The optionaltracestate header should be processed and propagated together with traceparentwhen applicable. tracestatecan be used to carry vendor-specific trace extensions, but its use should remain controlled to avoid interoperability issues.
This approach goes beyond simple correlation. Unlike a basic X-Correlation-id, traceparent supports hierarchical tracing (parent/child span relationships), which is essential for tracing complex distributed flows. In a chain of interactions the trace context is forwarded from the current interaction to the next interaction to ensure the end to end traceability.
In existing systems, a custom X-Correlation-ID header may be present. While this can be supported for backward compatibility, it should not replace traceparent.
Content Negotiation and Representation (Content-Type, Accept, Accept-Encoding, Content-Encoding)
The Content-Type header defines the format of the message payload (e.g. application/xml) and must always be set explicitly. This ensures that the receiving service can correctly interpret the payload without ambiguity.
The Accept header complements this by indicating which response formats the consumer is capable of handling. In well-defined APIs, this avoids implicit assumptions and makes the contract between consumer and provider explicit.
Inconsistent or missing usage of these headers is a common source of interoperability issues, particularly in environments where multiple providers implement the same service interface.
When HTTP interactions are bridged to AMQP, the same semantics must be preserved via the content-type property, ensuring that message consumers interpret the payload consistently regardless of the underlying transport protocol.
Compression is handled via:
Accept-Encoding: the consumer indicates supported compression formats such asgzip,deflate, orbrContent-Encoding: the provider indicates the encoding actually applied to the response payload
Supporting compression is particularly important for large payloads (e.g. MET data), as it significantly reduces bandwidth usage.
Message Size and Streaming Behaviour (Content-Length, Transfer-Encoding)
HTTP defines two key mechanisms for handling message size:
Content-Length, which specifies the exact size of the payload in bytesTransfer-Encoding: chunked, which allows streaming of large payloads when the total size is not known in advance
Services should handle both these mechanisms correctly. In particular:
consumers should not assume that
Content-Lengthis always presentservices should support chunked encoding for large or streaming responses
This is especially relevant for SWIM services dealing with large datasets or continuous data feeds.
Authentication and Authorization (Authorization)
Authentication should be handled using the standard Authorization header. This allows services to rely on widely supported security mechanisms and avoids the need for custom implementations.
Authentication information represents a trust boundary concern. As such:
it must always be validated by the receiving service, and
it must not be propagated blindly across multiple services.
For example, when an HTTP request triggers downstream processing via AMQP, the authentication context should not simply be copied into the message. Instead, services should establish their own trust model for asynchronous communication.
Retry and Resilience (Retry-After)
When a service is temporarily unavailable or rate-limited, it should use the Retry-After header to indicate how long the consumer should wait before retrying.
For example:
Retry-After: 120indicates a delay of 120 seconds before the next attempt
This is especially important in SWIM environments to avoid unnecessary load and ensure predictable, well-defined retry behaviour.
Security Headers (OWASP Alignment)
Security headers play a critical role in protecting services. Their systematic application to all HTTP communication is strongly recommended.
Strict-Transport-Security: max-age=63072000; includeSubDomains; preloadenforces HTTPS and prevents downgrade attacks by instructing consumers to never connect over insecure connections.Cache-Control: no-storeensures that sensitive data (e.g. flight plans, MET information) is never cached by intermediaries or clientX-Content-Type-Options: nosniffensures that browsers do not attempt to guess the content typeContent-Security-Policy: default-src 'none'restricts resource loading and mitigates cross-site scripting (XSS) risks.Referrer-Policy: strict-origin-when-cross-origincontrols the amount of information exposed in theRefererheader when navigating between origins (or domains).X-Frame-Options: SAMEORIGINprevents clickjacking by ensuring that content cannot be embedded in frames from external origins.Permissions-Policyenables fine-grained control over browser features (e.g. disabling access to sensors or camera).
Deprecated and Non-Recommended Headers
Some headers observed in existing implementations should not be used in new or updated services:
X-XSS-Protectionis deprecated and no longer supported by modern browsers, superseded byContent-Security-PolicyP3Pis obsolete and has no practical usefeature-policyis deprecated; superseded byPermissions-PolicyVendor-specific headers such as
x-oracle-dms-ecidorx-oracle-dms-ridshould be removed
Additionally, Set-Cookie should not be used to transport service-level metadata or session state, as this introduces unnecessary coupling and security risks.
Alignment with AMQP Properties
HTTP and AMQP serve different purposes and follow different messaging models. However, in many SWIM scenarios, a single logical flow spans both protocols. In such cases, alignment does not mean identical naming, but consistent semantics and end-to-end traceability. This ensures that the same operational flow can be tracked across both protocols, even though the underlying mechanisms differ. The following are envisaged scenarios:
Request-Driven Asynchronous Processing
This scenario corresponds to a service operation in which an incoming HTTP request triggers asynchronous processing via AMQP.
A typical example is:
A consumer invokes an API (e.g. to submit a flight update)
The service validates the request
The service publishes one or more messages to a broker for downstream processing
The HTTP request represents a single atomic transaction, even if part of the processing happens asynchronously.
To preserve traceability, the service should:
read the
traceparentheader from the incoming request,extract the trace identifier,
and propagate it into a dedicated AMQP Application property (
traceparent) when publishing messages.
This ensures that all downstream processing can be linked back to the original API call. If this mapping is not performed, the trace effectively stops at the HTTP boundary, and any asynchronous processing becomes disconnected from the initiating request.
Business correlation
While the traceparent property supports distributed tracing and observability, it should not be used as a substitute for business-level correlation. These are distinct concerns and should be handled separately.
The AMQP correlation-id property should be used whenever messages need to be associated with a business interaction or conversation spanning multiple exchanges. This is particularly relevant for asynchronous request/reply patterns, where the reply must be correlated with an earlier request.
For example, an HTTP request may initiate a process whose reply is delivered later through AMQP. In such cases, a business identifier associated with the original request should be propagated and used to populate the AMQP correlation-id, allowing the reply to be matched to the originating interaction.
Similarly, in messaging workflows implemented entirely over AMQP, the message-id of a request message is commonly copied into the correlation-id of the corresponding reply message. This allows request and reply messages to be unambiguously linked while remaining independent from the distributed tracing information carried by traceparent.
When a flow spans both HTTP and AMQP, it is therefore recommended to preserve both dimensions:
traceparentshould be propagated to support end-to-end tracing and troubleshooting;correlation-idshould be used to maintain the business relationship between related interactions.
This distinction ensures that operational tracing and business correlation remain independent concerns while complementing each other in end-to-end service interactions.
Event-Driven Service Interactions
In an event-driven architecture, services do not only react to direct requests but also emit events as part of their domain behaviour.
For example:
A service receives an HTTP request and updates its internal state
As a result, it emits a domain event (e.g. “FlightUpdated”)
Other services consume this event independently
In this scenario, the event is not merely a technical continuation of processing, but a first-class artefact representing a state change.
The key challenge here is not only to propagate a single trace, but to ensure that:
events can still be related to the originating context (when applicable),
while remaining meaningful as independent, reusable information units.
To achieve this:
when an event is triggered by an HTTP request, the originating
traceparentshould still be mapped to the AMQP headerwhen events originate internally services must generate new trace context (i.e. without an external request).
This distinction is important because not all events are tied to API calls, and forcing all events into a request-response trace model would be incorrect.
A consistent approach therefore enables tracing of full business flows across multiple services, while preserving the autonomy of event-driven interactions.
Property Catalogue
Property | Protocol | Usage Requirement | Description | Usage | Example value |
|---|---|---|---|---|---|
traceparent | HTTP | Required (propagate if present, generate if absent) | Carries the distributed trace identifier following W3C Trace Context, enabling end-to-end tracing across multiple services. | Must be propagated across all HTTP calls and should be mapped to AMQP header (via a custom |
|
tracestate | HTTP | Optional (when provided by upstream) | Carries vendor-specific trace extensions associated with the trace context | Use only if required and controlled |
|
correlation-id | AMQP | Conditional (required for correlated flows) | Identifies related messages in a flow and allows correlation of asynchronous processing steps | Use for message correlation in request/reply and asynchronous workflows. Note: When bridging HTTP to AMQP, application property |
|
Content-Type | Both | Required | Defines the media type of the payload (e.g. application/json, application/xml), allowing the receiver to correctly parse of the message body | Must always be explicitly set |
|
Accept | HTTP | Required | Specifies the media types that the consumers can process in the response | Ensures clear contracts between provider and consumers |
|
Authorization | HTTP | Required (at trust boundary) | Carries authentication credentials (e.g. Bearer token) used to authenticate | Must be validated by receiving service, not propagated blindly to downstream services |
|
Cache-Control | HTTP | Recommended (depending on data sensitivity) | Defines caching directives (e.g. no-store, max-age) controlling how responses are cached | Use for performance optimisation and to prevent caching of sensitive data |
|
Content-Encoding | HTTP | Conditional (when compression is used) | Indicates the encoding applied to the payload (e.g. gzip), allowing consumers to correctly decode compressed content | Use when payload compression is applied |
|
Accept-Encoding | HTTP | Recommended | Specifies which content encodings (e.g. gzip, deflate, br) the consumers can handle | Enables efficient compression negotiation |
|
Content-Length | HTTP | Required (unless Transfer-Encoding: chunked is used) | Specifies the exact size of the payload in bytes, allowing the receiver to determine message boundaries | Must be provided when chunked Transfer-Encoding is not used |
|
Transfer-Encoding | HTTP | Conditional (streaming scenarios) | Indicates that the payload is transmitted in chunks (e.g. chunked), allowing streaming of large or dynamic content | Use for large or streaming payloads where total size is not known in advance |
|
Retry-After | HTTP | Conditional (on 429 and 503 HTTP responses) | Indicates how long a consumers should wait before retrying after receiving a rate-limit or service-unavailable response | Use to control retry behaviour and protect services from unnecessary overload |
|
Strict-Transport-Security | HTTP | Recommended (security baseline) | Enforces HTTPS by instructing consumers to use only secure connections, preventing downgrade attacks | Should be systematically included in responses |
|
X-Content-Type-Options | HTTP | Recommended (security baseline) | Prevents browsers from MIME-sniffing responses, ensuring content is interpreted correctly | Set to “nosniff” |
|
Content-Security-Policy | HTTP | Recommended (security baseline) | Defines which resources can be loaded by the consumer, mitigating XSS and related injection attacks | Use restrictive policies (e.g. default-src 'none') |
|
Referrer-Policy | HTTP | Recommended (security baseline) | Controls how much referrer information is included in outgoing requests | Use strict policies such as “strict-origin-when-cross-origin” |
|
X-Frame-Options | HTTP | Recommended (security baseline) | Prevents content from being embedded in external frames, mitigating clickjacking attacks | Typically set to “SAMEORIGIN” |
|
Permissions-Policy | HTTP | Recommended (security baseline) | Controls access to browser/device features such as camera or geolocation | Disable all features not explicitly required by the service |
|
Security Considerations (OWASP)
HTTP headers are part of the external interface of a service and must therefore be treated as untrusted input. This means that all headers, including those used for tracing or routing, should be validated before being used.
In particular:
services should not blindly trust incoming trace identifiers,
sensitive information must never be exposed in headers,
and care must be taken to prevent header injection or manipulation.
At trust boundaries, it may be necessary to regenerate certain headers (e.g. tracing identifiers) to ensure integrity.
For further details, refer to: