gzip

Compresses responses with gzip.

Category GeneralAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin gzipPriority 995

What it does

gzip compresses the answers of the route on their way to the client. Only answers whose media type is listed under Types are compressed, text/html alone when the field is left empty, and only from Minimum length up.

In the example, a client that sends Accept-Encoding with gzip gets the HTML answer compressed, with Content-Encoding set to gzip. A JSON answer of 421 bytes, under the 1024 of Minimum length, keeps its Content-Length of 421.

When to use it

• An orders API whose JSON lists run to many kilobytes, read by a mobile app on slow networks.
• A backend that does not compress its own answers, where the gateway compresses them for the routes that carry the plugin.
• Large HTML or JSON reports sent compressed, while small answers go out as they are and cost no compression time.
• A cache in front of the gateway that must keep one copy per encoding, told so by Vary.

Not for keeping answers to serve again without asking the backend — see proxy-cache (Caches upstream responses on disk or in memory).

Set it up

Compress JSON and HTML responses larger than a kilobyte

Fill Types as in the JSON below, set Minimum length to 1024 and set Comp level to 5.

gzip · as the console saves it

{
  "types": [
    "application/json",
    "text/html"
  ],
  "min_length": 1024,
  "comp_level": 5
}

Things to know

• Minimum length — With 1024 here, an HTML answer is compressed and carries Content-Encoding with gzip, while a JSON answer of 421 bytes keeps its Content-Length of 421.
• Types — Every type is * written alone, not inside a list. A list that holds * would match no answer, and is refused when you save.
• Types — An item written with its parameters, text/plain; charset=utf-8 for example, would match no answer either, and is refused when you save.
• HTTP version — Only 1 and 1.1 are taken; 2 is refused when you save.
• Minimum length — An answer shorter than this is sent as it is, without a Content-Encoding header.
• AdviceStart with a middle Comp level, 5 as in the example, and raise it only when the smaller answers are worth the extra work per request.

Settings

The fields as the console shows them, section by section.

Typestypesarray of strings or stringdefault ["text/html"]

A JSON list of media types, such as ["application/json"], or "*" for every type. A charset after the type still matches. Left empty, only text/html is compressed.

one of * as a string · example ["text/html","application/json"]

Minimum lengthmin_lengthintegerdefault 20

The smallest answer, in bytes, worth compressing. It is read from the declared length, so an answer without one is always compressed.

at least 1

Comp levelcomp_levelintegerdefault 1

Compression level from 1, the fastest, to 9, the smallest output.

1 to 9

HTTP versionhttp_versionnumberdefault 1.1

The oldest HTTP version that gets compressed answers, where 1 means HTTP/1.0. Older requests are answered uncompressed.

one of 1, 1.1

Varyvaryboolean

Adds Vary: Accept-Encoding to a compressed answer, which tells a cache to keep one copy per encoding.

Buffersbuffersobjectdefault {"number":32,"size":4096}

The compressed answer is written through this many buffers of this many bytes.

Numberbuffers.numberintegerdefault 32

at least 1

Sizebuffers.sizeintegerdefault 4096

at least 1

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.