Skip to main content

Gzip Compression

The gzip plugin compresses eligible HTTP response bodies before the gateway sends them to clients. It can reduce bandwidth for text, JSON, and other compressible content on selected routes or services without changing the upstream application.

Response Eligibility​

The plugin configures response compression when these conditions are met:

ConditionBehavior
Client supportThe client advertises gzip with a nonzero quality value in Accept-Encoding.
Content typeThe response has Content-Type, and its MIME type matches types.
Response lengthIf the response includes a numeric Content-Length, it must be at least min_length. When Content-Length is absent, the plugin does not apply the minimum-length check.
HTTP versionThe client HTTP version is greater than or equal to http_version.
Response statusThe response status is 200, 403, or 404.
Existing encodingThe response does not already have a nonempty Content-Encoding header.
Response bodyThe response is a body-bearing main response.

The gateway's static gzip_proxied and gzip_disable policies can still prevent compression. Compressing a response removes Content-Length and Accept-Ranges and converts a strong ETag to a weak validator.

Examples​

The examples first compare identity-encoded and gzip-encoded responses and verify that decompression preserves the response body. The second example raises the minimum length so that the same response is no longer compressed.

Compress a Text Response​

The Docker-based setup uses a local plain-text upstream and requires a running APISIX or API7 Gateway container that can join a Docker network.

Create and enter a working directory for the example:

mkdir gzip-example
cd gzip-example

Create the following Python script for the test upstream:

gzip-upstream.py
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


class Handler(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1"

def do_GET(self):
if self.path != "/large-response":
self.send_error(404)
return

body = b"compressible response\n" * 256

self.send_response(200)
self.send_header("Content-Type", "text/plain; charset=utf-8")
self.send_header("Content-Length", str(len(body)))
self.send_header("Vary", "Origin")
self.end_headers()
self.wfile.write(body)

def log_message(self, *_):
pass


ThreadingHTTPServer(("0.0.0.0", 8000), Handler).serve_forever()

Set GATEWAY_CONTAINER to the running APISIX or API7 Gateway container. Create a dedicated network and connect the gateway to it:

export GATEWAY_CONTAINER=replace-with-gateway-container-name

docker network create gateway-gzip-net
docker network connect gateway-gzip-net "$GATEWAY_CONTAINER"

Start the test upstream:

docker run -d \
--name gzip-upstream \
--network gateway-gzip-net \
-v "$PWD/gzip-upstream.py:/gzip-upstream.py:ro" \
python:3.13.15-alpine3.24 \
python -u /gzip-upstream.py

Configure the plugin to compress sufficiently large plain-text responses and add the response-variance header.

If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY before using the Admin API tab.

Create the route:

curl "http://127.0.0.1:9180/apisix/admin/routes/gzip-route" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/large-response",
"plugins": {
"gzip": {
"types": ["text/plain"],
"min_length": 100,
"comp_level": 6,
"vary": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"gzip-upstream:8000": 1
}
}
}'

Save an identity-encoded response and a gzip-encoded response:

curl "http://127.0.0.1:9080/large-response" \
-H "Accept-Encoding: identity" \
--silent \
--show-error \
--fail \
--dump-header identity-headers.txt \
--output identity.txt

curl "http://127.0.0.1:9080/large-response" \
-H "Accept-Encoding: gzip" \
--silent \
--show-error \
--fail \
--dump-header gzip-headers.txt \
--output response.gz

Confirm that the second response is gzip encoded and varies by the request encoding:

grep -i "^Content-Encoding:" gzip-headers.txt
grep -i "^Vary:" gzip-headers.txt

The gzip-encoded response includes both headers:

Content-Encoding: gzip
Vary: Origin
Vary: Accept-Encoding

The gateway preserves the upstream variance and adds request-encoding variance for caches.

Decompress the response and compare it with the identity-encoded body:

if ! gzip -dc response.gz > decompressed.txt; then
echo "Decompression failed"
exit 1
fi

if cmp identity.txt decompressed.txt; then
echo "Bodies match"
else
echo "Bodies differ"
exit 1
fi

if [ "$(wc -c < response.gz)" -lt "$(wc -c < identity.txt)" ]; then
echo "Compressed response is smaller"
else
echo "Compressed response is not smaller"
exit 1
fi

The checks return:

Bodies match
Compressed response is smaller

The results confirm that compression preserves the response body and reduces its size for the highly compressible test content.

Skip Responses Below the Minimum Length​

Update the plugin from the previous example so that the test response is smaller than the configured minimum length:

curl "http://127.0.0.1:9180/apisix/admin/routes/gzip-route" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"plugins": {
"gzip": {
"types": ["text/plain"],
"min_length": 10000,
"comp_level": 6,
"vary": true
}
}
}'

Request gzip encoding again and check whether the response includes Content-Encoding:

if ! curl --silent --show-error --fail \
"http://127.0.0.1:9080/large-response" \
-H "Accept-Encoding: gzip" \
--dump-header min-length-headers.txt \
--output /dev/null; then
echo "Request failed" >&2
exit 1
fi

if grep -qi "^Content-Encoding: gzip" min-length-headers.txt; then
echo "Unexpected compressed response"
exit 1
else
echo "Response is not compressed"
fi

The check returns:

Response is not compressed

The response is not compressed because its declared length is below the updated threshold.