How do I set up an API Gateway API to handle binary data through a Lambda proxy integration?

Resolution

Note: API Gateway HTTP APIs automatically handle binary data. For API Gateway REST APIs to handle binary data, the backend Lambda function must use the output format of a Lambda function for proxy integration.

Use a Lambda proxy integration to return binary data through an API Gateway REST API

Complete the following steps:

1. Open the Lambda console.
2. Create a new Lambda function.
   Note: For an example Python 3 Lambda function, see Return binary media from a Lambda proxy integration in API Gateway.
3. Open the API Gateway console.
4. Create a new REST API.
5. To create a GET method for the new API, do the following:
   In the Methods panel, Choose Create method.
   For Method type, choose GET.
   In the / - GET - Setup section, for Integration type, choose Lambda function. Activate Use Lambda proxy integration.
   For Lambda function, choose the AWS Region that you created your Lambda function in. Then, enter the name of the new Lambda function.
   Choose Create method.
6. For API, choose API settings.
7. Under Binary media types, choose Manage media types, and then choose Add binary media type.
8. Add your file format, such as image/png or application/pdf.
9. Choose Save changes.
10. Deploy your API to a new stage.
    Note: For information about how to set up a new stage, see Set up a stage for a REST API in API Gateway.

For information about how to invoke your API, see Invoke REST APIs in API Gateway.

Note: For binary data, you must set the ;isBase64Encoded property to true in the Lambda function's output. The body property must also contain the base64-encoded binary media. For more information, see Binary media types for REST APIs in API Gateway.

Use Postman or cURL to invoke your REST API to return binary data

Important: For Postman or cURL, include the Accept header in the API request. The Accept header value must match the file format that you're using, such as image/png or application/pdf.

Run the following curl command:

curl 'https://exampleRestApiId.execute-api.exampleRegion.amazonaws.com/exampleStageName/' -H 'Accept: image/png'

Note: In the preceding command, replace exampleRestApiId with your API's identifier and exampleRegion with the Region that your API is in. Also, replace exampleStageName with your API's stage name and image/png, with your image file type.

Use a web browser to invoke your REST API to return binary data

Web browsers automatically send an Accept header with multiple values. By default, the first value is always html/text. Because API Gateway accepts only the first value, you must add text/html as a binary media type to the API. Otherwise, you get the following error message:

"The image "https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/" cannot be displayed because it contains errors."

To add text/html as a binary media type to a REST API, complete the following steps:

1. Open the API Gateway console.
2. Select your API.
3. In the navigation pane, choose API settings.
4. Under Binary media types, choose Manage media types, and then choose Add binary media type.
5. Enter text/html.
6. Chose Save changes.
7. Deploy your API.

For more information, see Content type conversions in API Gateway.