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:
| Condition | Behavior |
|---|---|
| Client support | The client advertises gzip with a nonzero quality value in Accept-Encoding. |
| Content type | The response has Content-Type, and its MIME type matches types. |
| Response length | If 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 version | The client HTTP version is greater than or equal to http_version. |
| Response status | The response status is 200, 403, or 404. |
| Existing encoding | The response does not already have a nonempty Content-Encoding header. |
| Response body | The 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:
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.
- Admin API
- ADC
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
}
}
}'
Configure ADC to connect to the target backend. The remaining ADC commands read the connection settings from these environment variables:
- APISIX
- API7 Gateway
If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY before configuring ADC.
export ADC_BACKEND=apisix
export ADC_SERVER="http://127.0.0.1:9180"
export ADC_TOKEN="${ADMIN_API_KEY}"
export ADC_BACKEND=api7ee
export ADC_SERVER="https://{DASHBOARD_ADDR}"
export ADC_TOKEN="{DASHBOARD_TOKEN}"
export ADC_GATEWAY_GROUP="{GATEWAY_GROUP}"
Create the service and route:
services:
- name: gzip-service
labels:
docs-example: gzip
routes:
- name: gzip-route
uris:
- /large-response
plugins:
gzip:
types:
- text/plain
min_length: 100
comp_level: 6
vary: true
upstream:
type: roundrobin
nodes:
- host: gzip-upstream
port: 8000
weight: 1
Preview the changes and confirm that they only affect resources for this example:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=gzip
Review diff.yaml, then synchronize the labeled service:
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=gzip
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:
- Admin API
- ADC
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
}
}
}'
In adc.yaml, increase the minimum length on the existing route:
plugins:
gzip:
types:
- text/plain
min_length: 10000
comp_level: 6
vary: true
Preview the updated file:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=gzip
Review diff.yaml, then synchronize the labeled service:
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=gzip
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.