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
the RestApi resource or set the contentHandling properties on
the Integration and the IntegrationResponse resources.
The contentHandling value can be CONVERT_TO_BINARY,
CONVERT_TO_TEXT, or undefined. Depending on the
contentHandling value, and whether the
Content-Type header of the response or the Accept
header of the incoming request matches an entry in the binaryMediaTypes
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 thecontentHandlingproperty are not defined, the payloads are handled as UTF-8 encoded JSON strings.Set the
contentHandlingproperty of the Integration resource toCONVERT_TO_BINARYto have the request payload converted from a Base64-encoded string to its binary blob, or set the property toCONVERT_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 theContent-Typeheader value matches one of thebinaryMediaTypesentries and the passthrough behaviors are also enabled for the API.Set the
contentHandlingproperty of the IntegrationResponse resource toCONVERT_TO_BINARYto have the response payload converted from a Base64-encoded string to its binary blob, or set the property toCONVERT_TO_TEXTto have the response payload converted from a binary blob to a Base64-encoded string. IfcontentHandlingis not defined, and if theContent-Typeheader of the response and theAcceptheader of the original request match an entry of thebinaryMediaTypeslist, API Gateway passes through the body. This occurs when theContent-Typeheader and theAcceptheader are the same; otherwise, API Gateway converts the response body to the type specified in theAcceptheader.



