Response compression

With server.compression.enabled=true, the server gzips text responses (HTML, JSON, CSS, JavaScript, ...) for clients that accept gzip.

Why

JSON and HTML shrink a lot with gzip, often to a fifth of their size. Smaller answers reach slow networks and phones sooner and cost less bandwidth.

Compression costs CPU on every answer, and small answers gain little. So it is off by default, and even when it is on, small answers and media types that are already compressed (images, video, archives) are sent as they are.

Leave it off when a proxy in front (nginx, a CDN) already compresses, or when you serve precompressed files (spring.web.resources.chain.compressed).

Example

# lib/resources/application.yml
server:
  compression:
    enabled: true
    mime-types:
      - text/html
      - text/css
      - text/javascript
      - application/javascript
      - application/json
      - application/problem+json
      - image/svg+xml
    min-response-size: 1KB
server.compression.enabled=true
server.compression.mime-types=text/html,text/css,text/javascript,application/javascript,application/json,application/problem+json,image/svg+xml
server.compression.min-response-size=1KB

A request and its answer:

GET /api/books HTTP/1.1
Accept-Encoding: gzip, br

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip
Vary: Accept-Encoding
Transfer-Encoding: chunked

Properties

Key Type Default Meaning
server.compression.enabled bool false Gzip the responses that qualify.
server.compression.mime-types List<String> Spring Boot's list (below) The media types compressed.
server.compression.min-response-size DataSize 2KB The smallest Content-Length compressed.

server.compression.enabled

server.compression.mime-types

text/html, text/xml, text/plain, text/css, text/javascript,
application/javascript, application/json, application/xml

server.compression.min-response-size

Which answers are compressed

An answer is compressed when all of these are true:

  1. server.compression.enabled is true;
  2. the client accepts gzip;
  3. the status allows a body: not 1xx, 204, 205 or 304;
  4. it is not partial content: not 206, no Content-Range;
  5. it has no Content-Encoding yet (a precompressed file is sent as it is);
  6. it has no strong ETag. A strong tag promises these exact bytes, so, as Tomcat does, such an answer is never compressed. A weak tag (W/"...", as the static resources send) is fine;
  7. its Content-Type is in mime-types;
  8. its Content-Length is at least min-response-size, or not known.

When the answer is compressed, Content-Encoding: gzip is added and Content-Length is dropped: the body is sent chunked.

Vary: Accept-Encoding

Every answer that rules 1 and 3 to 8 allow gets Vary: Accept-Encoding, even for a client that does not accept gzip. So a cache between the client and the server keeps the compressed and the plain answer apart. It is added once. When Vary already holds *, it stays *.

Streams

Only gzip

The server compresses with gzip only. No Brotli, no deflate. To serve Brotli, ship precompressed .br files next to the static files and set spring.web.resources.chain.compressed=true. See Static resources.

WebSocket

Compression does not apply to WebSocket messages, and the server does not negotiate permessage-deflate. See WebSocket.

In Spring (Java)

server.compression.enabled=true
server.compression.mime-types=text/html,application/json
server.compression.min-response-size=2KB

Differences that matter:

See also