Menu
Amazon API Gateway
Developer Guide

Enable Binary Support Using the API Gateway Console

The section explains how to enable binary support using the API Gateway console. As an example, we use an API integrated with Amazon S3. We focus on the tasks to set the supported media types and to specify how the payload should be handled. For detailed information on how to create an API integrated with Amazon S3, see Create an API as an Amazon S3 Proxy.

To enable binary support using the API Gateway console

  1. Set binary media types for the API:

    1. Create a new API or choose an existing API. For this example, we name the API FileMan.

    2. Choose Binary Support under the API.

    3. In the Binary Support pane, choose Edit.

    4. Choose Add binary media types and type a MIME type to be supported for your API.

    5. Choose Save.

      
                                        Add binary support in the API Gateway console.

  2. Set how message payloads are handled for the API method:

    1. Create a new or choose an existing resource in the API. For this example, we use the /{folder}/{item} resource.

    2. Create a new or choose an existing method on the resource. As an example, we use the GET /{folder}/{item} method integrated with the Object GET action in Amazon S3.

    3. In Content Handling, choose an option.

      
                                        Set up the GET method in the API Gateway
                                            console.

      Choose Passthrough if you do not want to convert the body when the client and back end accepts the same binary format. Choose Convert to text (if needed) to convert the binary body to a Base64-encoded string when, for example, the back end requires that a binary request payload is passed in as a JSON property. And choose Convert to binary (if needed) when the client submits a Base64-encoded string and the back end requires the original binary format, or when the endpoint returns a Base64-encoded string and the client accepts only the binary output.

    4. Preserve the incoming request's Accept header in the integration request. You should do this if you've set contentHandling to passthrough and want to override that setting at run time.

      
                                        Keep the Accept header in the
                                            integration request.

    5. Enable the passthrough behavior on the request body.

      
                                        Enable passthrough behavior for the request
                                            body.

    6. For conversion to text, define a mapping template to put the Base64-encoded binary data into the required format.

      
                                            Mapping template for the convert-to-text option.

      The format of this mapping template depends on the endpoint requirements of the input.