# Payload compression for REST APIs in API Gateway API Gateway allows your client to call your API with compressed payloads by using one of the [supported content codings](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). By default, API Gateway supports decompression of the method request payload. However, you must configure your API to enable compression of the method response payload. To enable compression on an [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), set the [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize) property to a non-negative integer between 0 and 10485760 (10M bytes) when you create the API or after you've created the API. To disable compression on the API, set the `minimumCompressionSize` to null or remove it altogether. You can enable or disable compression for an API by using the API Gateway console, the AWS CLI, or the API Gateway REST API. If you want the compression applied on a payload of any size, set the `minimumCompressionSize` value to zero. However, compressing data of a small size might actually increase the final data size. Furthermore, compression in API Gateway and decompression in the client might increase overall latency and require more computing times. You should run test cases against your API to determine an optimal value. The client can submit an API request with a compressed payload and an appropriate `Content-Encoding` header for API Gateway to decompress and apply applicable mapping templates, before passing the request to the integration endpoint. After the compression is enabled and the API is deployed, the client can receive an API response with a compressed payload if it specifies an appropriate `Accept-Encoding` header in the method request. When the integration endpoint expects and returns uncompressed JSON payloads, any mapping template that's configured for an uncompressed JSON payload is applicable to the compressed payload. For a compressed method request payload, API Gateway decompresses the payload, applies the mapping template, and passes the mapped request to the integration endpoint. For an uncompressed integration response payload, API Gateway applies the mapping template, compresses the mapped payload, and returns the compressed payload to the client. **Topics** + [ # Enable payload compression for an API in API Gateway ](api-gateway-enable-compression.md) + [ # Call an API method with a compressed payload in API Gateway ](api-gateway-make-request-with-compressed-payload.md) + [ # Receive an API response with a compressed payload in API Gateway ](api-gateway-receive-response-with-compressed-payload.md) # Enable payload compression for an API in API Gateway You can enable compression for an API using the API Gateway console, the AWS CLI, or an AWS SDK. For an existing API, you must deploy the API after enabling the compression in order for the change to take effect. For a new API, you can deploy the API after the API setup is complete. **Note** The highest-priority content encoding must be one supported by API Gateway. If it is not, compression is not applied to the response payload. **Topics** + [ ## Enable payload compression for an API using the API Gateway console ](#api-gateway-enable-compression-console) + [ ## Enable payload compression for an API using the AWS CLI ](#api-gateway-enable-compression-cli) + [ ## Content codings supported by API Gateway ](#api-gateway-supported-content-encodings) ## Enable payload compression for an API using the API Gateway console The following procedure describes how to enable payload compression for an API. **To enable payload compression by using the API Gateway console** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose an existing API or create a new one. 1. In the main navigation pane, choose **API settings**. 1. In the **API details** section, choose **Edit**. 1. Turn on **Content encoding** to enable payload compression. For **Minimum body size**, enter a number for the minimum compression size (in bytes). To turn off compression, turn off the **Content encoding** option. 1. Choose **Save changes**. ## Enable payload compression for an API using the AWS CLI The following [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) command creates an API with payload compression: ``` aws apigateway create-rest-api \ --name "My test API" \ --minimum-compression-size 0 ``` The following [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) command enables payload compression for an existing API: ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value=0 ``` The `minimumCompressionSize` property has a non-negative integer value between 0 and 10485760 (10M bytes). It measures the compression threshold. If the payload size is smaller than this value, compression or decompression are not applied on the payload. Setting it to zero allows compression for any payload size. The following [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) command turns off payload compression: ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value= ``` You can also set `value` to an empty string `""` or omit the `value` property altogether in the preceding call. ## Content codings supported by API Gateway API Gateway supports the following content codings: + `deflate` + `gzip` + `identity` API Gateway also supports the following `Accept-Encoding` header format, according to the [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4) specification: + `Accept-Encoding:deflate,gzip` + `Accept-Encoding:` + `Accept-Encoding:*` + `Accept-Encoding:deflate;q=0.5,gzip;q=1.0` + `Accept-Encoding:gzip;q=1.0,identity;q=0.5,*;q=0` # Call an API method with a compressed payload in API Gateway To make an API request with a compressed payload, the client must set the `Content-Encoding` header with one of the [supported content codings](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). Suppose that you're an API client and want to call the PetStore API method (`POST /pets`). Don't call the method by using the following JSON output: ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Length: ... { "type": "dog", "price": 249.99 } ``` Instead, you can call the method with the same payload compressed by using the GZIP coding: ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Encoding:gzip Content-Length: ... ���RPP*�,HU�RPJ�OW��e&���L,�,-y�j ``` When API Gateway receives the request, it verifies if the specified content coding is supported. Then, it attempts to decompress the payload with the specified content coding. If the decompression is successful, it dispatches the request to the integration endpoint. If the specified coding isn't supported or the supplied payload isn't compressed with specified coding, API Gateway returns the `415 Unsupported Media Type` error response. The error is not logged to CloudWatch Logs, if it occurs in the early phase of decompression before your API and stage are identified. # Receive an API response with a compressed payload in API Gateway When making a request on a compression-enabled API, the client can choose to receive a compressed response payload of a specific format by specifying an `Accept-Encoding` header with a [supported content coding](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). API Gateway only compresses the response payload when the following conditions are satisfied: + The incoming request has the `Accept-Encoding` header with a supported content coding and format. **Note** If the header is not set, the default value is `*` as defined in [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4). In such a case, API Gateway does not compress the payload. Some browser or client may add `Accept-Encoding` (for example, `Accept-Encoding:gzip, deflate, br`) automatically to compression-enabled requests. This can turn on the payload compression in API Gateway. Without an explicit specification of supported `Accept-Encoding` header values, API Gateway does not compress the payload. + The `minimumCompressionSize` is set on the API to enable compression. + The integration response doesn't have a `Content-Encoding` header. + The size of an integration response payload, after the applicable mapping template is applied, is greater than or equal to the specified `minimumCompressionSize` value. API Gateway applies any mapping template that's configured for the integration response before compressing the payload. If the integration response contains a `Content-Encoding` header, API Gateway assumes that the integration response payload is already compressed and skips the compression processing. An example is the PetStore API example and the following request: ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept: application/json ``` The backend responds to the request with an uncompressed JSON payload that's similar to the following: ``` 200 OK [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` To receive this output as a compressed payload, your API client can submit a request as follows: ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept-Encoding:gzip ``` The client receives the response with a `Content-Encoding` header and GZIP-encoded payload that are similar to the following: ``` 200 OK Content-Encoding:gzip ... ���RP� J�)JV �:P^IeA*������+(�L �X�YZ�ku0L0B7!9��C#�&����Y��a���^�X ``` When the response payload is compressed, only the compressed data size is billed for data transfer.