Nginx Gzip vs Brotli Compression for JSON APIs

For JSON APIs, gzip is the safe, universally supported default, while Brotli often compresses slightly better at comparable levels but needs an extra Nginx module and more CPU at high settings. The best choice depends on payload size, traffic, and CPU budget. Moderate compression levels usually deliver most of the benefit, and tiny responses are often not worth compressing at all.

How Does Compression Help a JSON API?

JSON is verbose text with repeated keys and structure, so it compresses very well. Compression reduces bytes on the wire, which lowers transfer time on slower networks and reduces bandwidth costs. The client announces supported encodings in the Accept-Encoding header, and the server picks one and replies with Content-Encoding.

The trade-off is CPU time. Compressing each response costs processing power on the server, and decompression costs some on the client. For large list responses the savings are significant. For tiny payloads, such as a short status object, the overhead can outweigh the benefit, and the compressed result may even be larger than the original.

What Are the Differences Between Gzip and Brotli?

Gzip uses the DEFLATE algorithm and is supported by essentially every HTTP client and Nginx build through the standard module. Brotli uses a more modern algorithm with a built-in dictionary of common web content, and it frequently yields smaller output at similar quality settings.

• Support: gzip works everywhere. Brotli is widely supported in browsers, but support in other HTTP clients, SDKs, and mobile libraries varies, so check yours.
• Setup: gzip ships with Nginx. Brotli typically requires a third-party module or a build that includes it.
• CPU cost: Brotli at high levels is considerably slower to compress than gzip. At low levels, the gap narrows.
• Static vs dynamic: Brotli shines for precompressed static files. For dynamic API responses, compression time directly adds latency.

Brotli is also commonly limited to secure connections by browsers, so it matters mostly for HTTPS traffic.

How Do You Configure Compression in Nginx?

Enable compression only for text-like types, set a minimum size, and avoid very high levels for dynamic content.

gzip on;
gzip_comp_level 5;
gzip_min_length 1024;
gzip_types application/json application/problem+json;
gzip_vary on;
gzip_proxied any;

The Vary: Accept-Encoding header is important. It tells caches that the response differs by encoding, which prevents a cache from serving a compressed response to a client that cannot decode it. Check the module documentation for the directives available in your version, since Brotli directives depend on the module you install.

If your application or an upstream service already compresses responses, avoid compressing twice. Decide which layer is responsible and disable the other, so you do not waste CPU on data that will not shrink further.

Which One Should You Choose for an API?

Start with gzip at a moderate level. It is simple, universal, and delivers most of the gain. Add Brotli if your clients support it, you control the deployment, and measurements show a worthwhile reduction in bytes without hurting latency.

Measure with realistic payloads. Compare compressed size, response time at your typical concurrency, and CPU usage across a few levels. Many teams find that the differences between algorithms matter less than avoiding compression of small responses and choosing a sensible level. Also consider a CDN or edge layer that can handle compression for you, if you use one.

Frequently Asked Questions

Should I compress every API response?

No. Skip very small responses, already compressed content such as images, and anything where latency matters more than bytes. A minimum length setting handles the small ones.

Is Brotli always smaller than gzip?

Often, but not always, and the gain depends on the data and settings. Test with your own payloads.

Does compression create security risks?

Compressing responses that mix secrets with attacker-influenced data can enable attacks such as BREACH. Review this risk for sensitive pages, and consult security guidance for your case.

What compression level is a good default?

For dynamic responses, a mid level such as 4 to 6 for gzip is a common starting point. Adjust based on measurements.

Summary

Gzip is the dependable default for JSON APIs, and Brotli can add savings where it is supported and the CPU cost is acceptable. Compress only worthwhile responses, set the Vary header, and measure before changing levels. Confirm module details in the Nginx documentation.