How do I set up an API Gateway API to handle binary data using 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 correct output format of a Lambda function for proxy integration.

To return binary data through an API Gateway REST API using a Lambda proxy integration

1.    In the Lambda console, create a new Lambda function.
Note: For an example Python 3 Lambda function, see Return binary media from a Lambda proxy integration.

2.    In the API Gateway console, create a new REST API.

3.    Create a GET method for the new API by doing the following:
In the Resources panel, choose Actions.
Choose Create Method. Then, choose GET.
In the / - GET - Setup section, for Integration type, choose Lambda Function. Choose the Use Lambda Proxy integration check box.
For Lambda Region, choose the region that you created your Lambda function in.
For Lambda Function, enter the name of the Lambda function that you created in step 1.
Choose Save.
In the Add Permission to Lambda Function dialog box that appears, choose OK.

4.    In the left navigation pane, in the API section, choose Settings.

5.    Under Binary Media Types, choose Add Binary Media Type and add image/png or another file format that you'd like to use, such as application/pdf.

6.    Choose Save Changes.

7.    Deploy your API to a new stage. For more information, see Setting up a stage using the API Gateway console.

Your API is now ready to return binary data through API Gateway using a Lambda proxy integration. For information on how to invoke your API, see Invoking a REST API in Amazon API Gateway.

Note: When dealing with binary data, the ;isBase64Encoded property in the output of the Lambda function must be set to true. The body property must also contain the base64 encoded binary media. For more information, see Working with binary media types for REST APIs .

To invoke your REST API to return binary data using Postman and cURL

Important: If you use Postman or cURL to invoke your REST API to return binary data, make sure to include the Accept header in the API request. The Accept header value needs to match whatever file format you're using. For example, image/png or application/pdf.

For information on how to invoke a REST API using Postman, see Use Postman to call a REST API.

For information on how API Gateway encodes payloads, see Content type conversions in API Gateway.

Example cURL command to invoke an API Gateway REST API to return binary data

$ curl 'https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/' -H 'Accept: image/png'

Note: Replace the following variables before running the example cURL command:
For {restapi_id}, enter your API's identifier.
For {region}, enter the AWS Region that your API is in.
For {stage_name}, enter your API's stage name.
For image/png, make sure that you enter the actual image file type that you're using.

To invoke your REST API to return binary data using a web browser

If you use a web browser to invoke a REST API to return binary data, make sure that you add text/html as a binary media type to the API.

Note: Web browsers automatically send an Accept header with multiple values. By default, the first value is always html/text. Because API Gateway honors the first value only, you must add text/html as a binary media type to the API. Otherwise, you'll 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, do the following:

1.    In the API Gateway console, choose your API.

2.    In the left navigation pane, at the bottom of the API section, choose Settings.

3.    Under Binary Media Types, choose Add Binary Media Type and add text/html.

4.    Chose Save Changes.

5.     Deploy your API.

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

---