Content type conversions in API Gateway
The combination of your API's binaryMediaTypes, the headers in client
requests, and the integration contentHandling property determine how API Gateway
encodes payloads.
The following table shows how API Gateway converts the request payload for specific
configurations of a request's Content-Type header, the
binaryMediaTypes list of a RestApi resource, and the contentHandling property value of the Integration resource.
| Method request payload | Request Content-Type header |
binaryMediaTypes |
contentHandling |
Integration request payload |
|---|---|---|---|---|
| Text data | Any data type | Undefined | Undefined | UTF8-encoded string |
| Text data | Any data type | Undefined | CONVERT_TO_BINARY |
Base64-decoded binary blob |
| Text data | Any data type | Undefined | CONVERT_TO_TEXT |
UTF8-encoded string |
| Text data | A text data type | Set with matching media types | Undefined | Text data |
| Text data | A text data type | Set with matching media types | CONVERT_TO_BINARY |
Base64-decoded binary blob |
| Text data | A text data type | Set with matching media types | CONVERT_TO_TEXT |
Text data |
| Binary data | A binary data type | Set with matching media types | Undefined | Binary data |
| Binary data | A binary data type | Set with matching media types | CONVERT_TO_BINARY |
Binary data |
| Binary data | A binary data type | Set with matching media types | CONVERT_TO_TEXT |
Base64-encoded string |
The following table shows how API Gateway converts the response payload for specific
configurations of a request's Accept header, the binaryMediaTypes list of a RestApi resource, and the contentHandling property value of the IntegrationResponse
resource.
Important
When a request contains multiple media types in its Accept header, API Gateway honors only the first Accept media type. If you can't control the order of the Accept media types and the media type of your binary
content isn't the first in the list, add the first Accept media type in the binaryMediaTypes list of your API. API Gateway handles all content types in
this list as binary.
For example, to send a JPEG file using an <img> element in a browser, the browser might send Accept:image/webp,image/*,*/*;q=0.8 in a request. By
adding image/webp to the binaryMediaTypes list, the endpoint receives the JPEG file as binary.
| Integration response payload | Request Accept header |
binaryMediaTypes |
contentHandling |
Method response payload |
|---|---|---|---|---|
| Text or binary data | A text type | Undefined | Undefined | UTF8-encoded string |
| Text or binary data | A text type | Undefined | CONVERT_TO_BINARY |
Base64-decoded blob |
| Text or binary data | A text type | Undefined | CONVERT_TO_TEXT |
UTF8-encoded string |
| Text data | A text type | Set with matching media types | Undefined | Text data |
| Text data | A text type | Set with matching media types | CONVERT_TO_BINARY |
Base64-decoded blob |
| Text data | A text type | Set with matching media types | CONVERT_TO_TEXT |
UTF8-encoded string |
| Text data | A binary type | Set with matching media types | Undefined | Base64-decoded blob |
| Text data | A binary type | Set with matching media types | CONVERT_TO_BINARY |
Base64-decoded blob |
| Text data | A binary type | Set with matching media types | CONVERT_TO_TEXT |
UTF8-encoded string |
| Binary data | A text type | Set with matching media types | Undefined | Base64-encoded string |
| Binary data | A text type | Set with matching media types | CONVERT_TO_BINARY |
Binary data |
| Binary data | A text type | Set with matching media types | CONVERT_TO_TEXT |
Base64-encoded string |
| Binary data | A binary type | Set with matching media types | Undefined | Binary data |
| Binary data | A binary type | Set with matching media types | CONVERT_TO_BINARY |
Binary data |
| Binary data | A binary type | Set with matching media types | CONVERT_TO_TEXT |
Base64-encoded string |
When converting a text payload to a binary blob, API Gateway assumes that the text data is a
base64-encoded string and outputs the binary data as a base64-decoded blob. If the
conversion fails, it returns a 500 response, which
indicates an API configuration error. You don't provide a mapping template for such a
conversion, although you must enable the passthrough behaviors on the
API.
When converting a binary payload to a text string, API Gateway always applies a base64
encoding on the binary data. You can define a mapping template for such a payload, but
can only access the base64-encoded string in the mapping template through $input.body, as shown in the following excerpt of an
example mapping template.
{ "data": "$input.body" }
To have the binary payload passed through without modification, you must enable the passthrough behaviors on the API.
