Enabling binary support using the API Gateway console - Amazon API Gateway
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Enabling 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 that is 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 Tutorial: Create a REST API as an Amazon S3 proxy in API Gateway.

To enable binary support by 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. Under the selected API in the primary navigation panel, choose Settings.

    3. In the Settings pane, choose Add Binary Media Type in the Binary Media Types section.

    4. Type a required media type, for example, image/png, in the input text field. If needed, repeat this step to add more media types. To support all binary media types, specify */*.

    5. Choose Save Changes.

  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.

      Choose Passthrough if you don't want to convert the body when the client and backend 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 backend 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 backend 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 runtime.

    5. Enable the passthrough behavior on the request body.

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

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