Enable Support for Binary Payloads in API Gateway
In API Gateway, the API request and response can have a text or binary payload. By default,
API Gateway treats the message body as a
UTF-8-encoded JSON string. For API Gateway
to handle binary payloads, you add the media types to the binaryMediaTypes list of
RestApi resource or set the contentHandling properties on
the Integration and the IntegrationResponse resources.
contentHandling value can be
CONVERT_TO_TEXT, or undefined. Depending on the
contentHandling value, and whether the
Content-Type header of the response or the
header of the incoming request matches an entry in the
list, API Gateway can encode the raw binary bytes as a Base64-encoded string, decode a
Base64-encoded string back to its raw bytes, or pass the body through without modification.
You must configure the API as follows to support binary payloads for your API in API Gateway:
Add the desired binary media types to the
binaryMediaTypeslist on the RestApi resource. If this property and the
contentHandlingproperty are not defined, the payloads are handled as UTF-8 encoded JSON strings.
contentHandlingproperty of the Integration resource to
CONVERT_TO_BINARYto have the request payload converted from a Base64-encoded string to its binary blob, or set the property to
CONVERT_TO_TEXTto have the request payload converted from a binary blob to a Base64-encoded string. If this property is not defined, API Gateway passes the payload through without modification. This occurs when the
Content-Typeheader value matches one of the
binaryMediaTypesentries and the passthrough behaviors are also enabled for the API.
contentHandlingproperty of the IntegrationResponse resource to
CONVERT_TO_BINARYto have the response payload converted from a Base64-encoded string to its binary blob, or set the property to
CONVERT_TO_TEXTto have the response payload converted from a binary blob to a Base64-encoded string. If
contentHandlingis not defined, and if the
Content-Typeheader of the response and the
Acceptheader of the original request match an entry of the
binaryMediaTypeslist, API Gateway passes through the body. This occurs when the
Content-Typeheader and the
Acceptheader are the same; otherwise, API Gateway converts the response body to the type specified in the