Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The API Gateway automatically manages content compression and decompression in the message flow between the client and the Backend API. This ensures:
  • Policies always operate on plain (uncompressed) text
  • Responses are automatically compressed based on the client’s supported methods
  • Correct processing regardless of the Backend API’s response format
This page explains how compression/decompression works at the gateway level. For information about policy placement and execution order in the message flow, see Message Processing and Policy Application.

​
Supported Compression Methods

MethodContent-Encoding ValueDescription
gzipgzipMost common method. Supported by all browsers and HTTP clients.
deflatedeflatezlib format compression. Less common than gzip.
BrotlibrDeveloped by Google, offers high compression ratios.
ZstandardzstdDeveloped by Facebook, good balance of speed and compression ratio.
compresscompressLegacy LZW-based method. Only decompression is supported; compression is not available.
identityidentityNo compression. Deprecated per RFC 9110.

​
Request Flow

A compressed request message from the client goes through the following stages: 
CLIENT                            GATEWAY                              BACKEND API
   │                                │                                      │
   │  ── Request (CE: gzip) ─────>  │                                      │
   │                                │  1. Detect compression (gzip)        ���
   │                                │  2. Decompress message               │
   │                                │  3. Apply policies (plain text)      │
   │                                │  4. Re-compress (gzip)               │
   │                                │  ── Request (CE: gzip) ──────────>   │
   │                                │                                      │

​
Stages

1

Compression Detection

The Content-Encoding header in the request message is read and the compression method is identified. In addition to the header value, the first bytes of the message content are checked to verify that it is actually compressed.
2

Decompression

The message content is decompressed according to the identified method. If decompression fails, the message is left as-is.
3

Policy Application

Request policies operate on the decompressed plain text. This allows transformation, validation, and filtering policies to work independently of the compression method.
4

Re-compression

After policies are applied, the message is re-compressed using the original compression method and sent to the Backend API.
Exceptions: Compression is not applied to multipart/form-data requests because decompression would break the multipart boundary structure.

​
Stacked Compression

A request message may contain multiple layers of compression (e.g., Content-Encoding: gzip, br). In this case, the gateway decompresses layers from right to left: first Brotli, then gzip. The message is sent to the Backend API as plain text.

​
Response Flow

The response message from the Backend API is processed based on the client’s Accept-Encoding header: 
BACKEND API                       GATEWAY                              CLIENT
   │                                │                                      │
   │  ── Response (CE: deflate) ─>  │                                      │
   │                                │  1. Detect compression (deflate)     │
   │                                │  2. Decompress message               │
   │                                │  3. Apply policies (plain text)      │
   │                                │  4. Check client AE (accepts gzip)   │
   │                                │  5. Compress with gzip               │
   │                                │  ── Response (CE: gzip) ─────────>   │
   │                                │                                      │

​
Encoding Selection Order

When the client’s Accept-Encoding header includes multiple methods, the gateway selects using the following fixed order:
  1. gzip
  2. deflate
  3. br (Brotli)
  4. zstd (Zstandard)
The q-value (quality) values in the Accept-Encoding header are currently not considered. This is consistent behavior with other gateways in the industry, including Nginx.

​
Accept-Encoding: * (Wildcard)

When the client sends Accept-Encoding: *, the gateway interprets this as “I accept all methods” and selects the most appropriate method according to the order above (RFC 9110 §12.5.3 compliant).

​
Binary Content Behavior

Binary content such as images, videos, and PDFs is processed differently from text content:
In proxies with download enabled, binary content is delivered to the client via streaming. In this mode:
  • Content is not held in memory; it is transferred in chunks
  • Memory consumption remains minimal for large files
  • If the client doesn’t support the compression method, content is automatically decompressed
  • Policies cannot modify the response body (content has already started being sent)
In proxies with download disabled, binary content is converted to Base64 format and enters the policy pipeline. Policies work on the Base64-encoded text. The original binary format is restored when sending to the client.

​
Charset & Encoding Override

The automatic compression behavior described above can be overridden per route using the Charset & Encoding Override settings in the Routing configuration. When an override is configured, the gateway ignores the Content-Encoding and Content-Type charset values and applies the configured value instead. This is useful when:
  • The Backend API returns compressed content without a Content-Encoding header
  • The declared charset in Content-Type does not match the actual encoding of the content
  • A specific compression method must be applied to the outgoing request or response regardless of content headers
Overrides are configured separately for two directions:
DirectionAvailable Overrides
Request Line (Client → Backend)Charset Override, Decompress Override, Compress Override
Response Line (Backend → Client)Charset Override, Decompress Override, Compress Override
Select Not Apply (skip) to explicitly skip compression or decompression for that direction. Supported encoding options: GZIP, DEFLATE, BR (Brotli), ZSTD, Not Apply (skip).
For full configuration details, see HTTP Routing — Charset & Encoding Override.

​
no-transform Behavior

When the Backend API sends a Cache-Control: no-transform header in its response, the gateway performs no compression or decompression transformation on the content:
  • The Backend’s compression method and content are forwarded to the client as-is
  • The Content-Encoding header is not modified
  • Vary and Warning headers are not added
This behavior is important for maintaining consistency across CDN and caching layers.

​
Automatically Added Headers

When the gateway applies a compression transformation, it automatically adds two headers to the response:
HeaderValueDescription
VaryAccept-EncodingInforms caching layers that the response varies based on the client’s encoding preference
Warning214 - "Transformation Applied"Indicates that a transformation was applied to the content (RFC 9111 §5.5)

​
Limitations and Known Behaviors

The gateway does not consider q-value preferences in the client’s Accept-Encoding header. For example, if the client sends br;q=1.0, gzip;q=0.5, the gateway selects gzip instead of Brotli. This is consistent behavior with Nginx and most gateways.
Brotli compression has no distinguishing byte sequence (magic bytes). Brotli content cannot be detected without a Content-Encoding header.
Stacked compression is partially supported for binary content. While all layers are decompressed sequentially for text content, only the outer layer is processed in binary streaming mode.
If the client sends Accept-Encoding: identity;q=0 (meaning “I don’t want uncompressed content”), per RFC 9110 the gateway could return a 406 response. However, consistent with Nginx and other gateways, the gateway responds with plain text and does not return 406.
When download is active, binary content is sent via streaming. In this mode, response policies cannot modify the message body because the content has already started being transmitted to the client. Request policies are not affected by this limitation.

​
Next Steps

Message Processing and Policy Application

Learn about policy placement and execution order in the message flow

Routing and Upstream

Learn about Backend API routing and load balancing settings

What is a Policy?

Learn about the policy concept and types

API Gateway

Learn about the API Gateway component architecture