# Binary media types for REST APIs in API Gateway Binary media types In API Gateway, the API request and response have a text or binary payload. A text payload is a `UTF-8`-encoded JSON string. A binary payload is anything other than a text payload. The binary payload can be, for example, a JPEG file, a GZip file, or an XML file. The API configuration required to support binary media depends on whether your API uses proxy or non-proxy integrations. If you use a proxy integration with payload response streaming, you don't need to configure your binary media types. For more information, see [Stream the integration response for your proxy integrations in API Gateway](response-transfer-mode.md). ## AWS Lambda proxy integrations To handle binary payloads for AWS Lambda proxy integrations, you must base64-encode your function's response. You must also configure the [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) for your API. Your API's `binaryMediaTypes` configuration is a list of content types that your API treats as binary data. Example binary media types include `image/png` or `application/octet-stream`. You can use the wildcard character (`*`) to cover multiple media types. API Gateway uses the first `Accept` header from clients to determine if a response should return binary media. To return binary media when you can't control the order of `Accept` header values, such as requests from a browser, set your API's binary media types to `*/*`. For example code, see [Return binary media from a Lambda proxy integration in API Gateway](lambda-proxy-binary-media.md). If you use a Lambda proxy integration with payload response streaming, you don't need to configure your binary media types. For more information, see [Set up a Lambda proxy integration with payload response streaming in API Gateway](response-transfer-mode-lambda.md). ## Non-proxy integrations To handle binary payloads for non-proxy integrations, you add the media types to the [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) list of the `RestApi` resource. Your API's `binaryMediaTypes` configuration is a list of content types that your API treats as binary data. Alternatively, you can set the [contentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) properties on the [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) and the [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) resources. The `contentHandling` value can be `CONVERT_TO_BINARY`, `CONVERT_TO_TEXT`, or undefined. **Note** For `MOCK` or private integrations, setting the `contentHandling` properties isn't supported in the AWS Management Console. You must use the AWS CLI, CloudFormation, or an SDK to set the `contentHandling` properties. Depending on the `contentHandling` value, and whether the `Content-Type` header of the response or the `Accept` header of the incoming request matches an entry in the `binaryMediaTypes` list, API Gateway can encode the raw binary bytes as a base64-encoded string, decode a base64-encoded string back to its raw bytes, or pass the body through without modification. You must configure the API as follows to support binary payloads for your API in API Gateway: + Add the desired binary media types to the `binaryMediaTypes` list on the [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) resource. If this property and the `contentHandling` property are not defined, the payloads are handled as UTF-8 encoded JSON strings. + Address the `contentHandling` property of the [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) resource. + To have the request payload converted from a base64-encoded string to its binary blob, set the property to `CONVERT_TO_BINARY`. + To have the request payload converted from a binary blob to a base64-encoded string, set the property to `CONVERT_TO_TEXT`. + To pass the payload through without modification, leave the property undefined. To pass a binary payload through without modification, you must also ensure that the `Content-Type` matches one of the `binaryMediaTypes` entries, and that [passthrough behaviors](integration-passthrough-behaviors.md) are enabled for the API. + Set the `contentHandling` property of the [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) resource. The `contentHandling` property, `Accept` header in client requests, and your API's `binaryMediaTypes` combined determine how API Gateway handles content type conversions. For details, see [Content type conversions in API Gateway](api-gateway-payload-encodings-workflow.md). **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 `` 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. For detailed information about how API Gateway handles the text and binary payloads, see [Content type conversions in API Gateway](api-gateway-payload-encodings-workflow.md). # 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](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) resource, and the `contentHandling` property value of the [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 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\$1TO\$1BINARY | Base64-decoded binary blob | | Text data | Any data type | Undefined | CONVERT\$1TO\$1TEXT | 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\$1TO\$1BINARY | Base64-decoded binary blob | | Text data | A text data type | Set with matching media types | CONVERT\$1TO\$1TEXT | 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\$1TO\$1BINARY | Binary data | | Binary data | A binary data type | Set with matching media types | CONVERT\$1TO\$1TEXT | 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](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) resource, and the `contentHandling` property value of the [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 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 `` 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\$1TO\$1BINARY | Base64-decoded blob | | Text or binary data | A text type | Undefined | CONVERT\$1TO\$1TEXT | 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\$1TO\$1BINARY | Base64-decoded blob | | Text data | A text type | Set with matching media types | CONVERT\$1TO\$1TEXT | 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\$1TO\$1BINARY | Base64-decoded blob | | Text data | A binary type | Set with matching media types | CONVERT\$1TO\$1TEXT | 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\$1TO\$1BINARY | Binary data | | Binary data | A text type | Set with matching media types | CONVERT\$1TO\$1TEXT | 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\$1TO\$1BINARY | Binary data | | Binary data | A binary type | Set with matching media types | CONVERT\$1TO\$1TEXT | 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](integration-passthrough-behaviors.md) 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](integration-passthrough-behaviors.md) on the API. # 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](integrating-api-with-aws-services-s3.md). **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`. 1. Under the selected API in the primary navigation panel, choose **API settings**. 1. In the **API settings** pane, choose **Manage media types** in the **Binary Media Types** section. 1. Choose **Add binary media type**. 1. Enter 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 `*/*`. 1. Choose **Save changes**. 1. 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. 1. 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. 1. For **Content handling**, choose an option. ![\[Set up the GET method in the API Gateway console.\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png) 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** 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** 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. 1. For **Request body passthrough**, choose **When there are no templates defined (recommended)** to enable the passthrough behavior on the request body. You could also choose **Never**. This means that the API will reject data with content-types that do not have a mapping template. 1. 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. ![\[Keep the Accept header in the integration request.\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png) 1. For conversion to text, define a mapping template to put the base64-encoded binary data into the required format. An example of a mapping template to convert to text is the following: ``` { "operation": "thumbnail", "base64Image": "$input.body" } ``` The format of this mapping template depends on the endpoint requirements of the input. 1. Choose **Save**. # Enabling binary support using the API Gateway REST API The following tasks show how to enable binary support using the API Gateway REST API calls. **Topics** + [ ## Add and update supported binary media types to an API ](#api-gateway-payload-encodings-setup-with-api-set-encodings-map) + [ ## Configure request payload conversions ](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding) + [ ## Configure response payload conversions ](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding) + [ ## Convert binary data to text data ](#api-gateway-payload-encodings-convert-binary-to-string) + [ ## Convert text data to a binary payload ](#api-gateway-payload-encodings-convert-string-to-binary) + [ ## Pass through a binary payload ](#api-gateway-payload-encodings-pass-binary-as-is) ## Add and update supported binary media types to an API To enable API Gateway to support a new binary media type, you must add the binary media type to the `binaryMediaTypes` list of the `RestApi` resource. For example, to have API Gateway handle JPEG images, submit a `PATCH` request to the `RestApi` resource: ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/image~1jpeg" } ] } ``` The MIME type specification of `image/jpeg` that is part of the `path` property value is escaped as `image~1jpeg`. To update the supported binary media types, replace or remove the media type from the `binaryMediaTypes` list of the `RestApi` resource. For example, to change binary support from JPEG files to raw bytes, submit a `PATCH` request to the `RestApi` resource, as follows: ``` PATCH /restapis/ { "patchOperations" : [{ "op" : "replace", "path" : "/binaryMediaTypes/image~1jpeg", "value" : "application/octet-stream" }, { "op" : "remove", "path" : "/binaryMediaTypes/image~1jpeg" }] } ``` ## Configure request payload conversions If the endpoint requires a binary input, set the `contentHandling` property of the `Integration` resource to `CONVERT_TO_BINARY`. To do so, submit a `PATCH` request, as follows: ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] } ``` ## Configure response payload conversions If the client accepts the result as a binary blob instead of a base64-encoded payload returned from the endpoint, set the `contentHandling` property of the `IntegrationResponse` resource to `CONVERT_TO_BINARY`. To do this, submit a `PATCH` request, as follows: ``` PATCH /restapis//resources//methods//integration/responses/ { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] } ``` ## Convert binary data to text data To send binary data as a JSON property of the input to AWS Lambda or Kinesis through API Gateway, do the following: 1. Enable the binary payload support of the API by adding the new binary media type of `application/octet-stream` to the API's `binaryMediaTypes` list. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] } ``` 1. Set `CONVERT_TO_TEXT` on the `contentHandling` property of the `Integration` resource and provide a mapping template to assign the base64-encoded string of the binary data to a JSON property. In the following example, the JSON property is `body` and `$input.body` holds the base64-encoded string. ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_TEXT" }, { "op" : "add", "path" : "/requestTemplates/application~1octet-stream", "value" : "{\"body\": \"$input.body\"}" } ] } ``` ## Convert text data to a binary payload Suppose a Lambda function returns an image file as a base64-encoded string. To pass this binary output to the client through API Gateway, do the following: 1. Update the API's `binaryMediaTypes` list by adding the binary media type of `application/octet-stream`, if it is not already in the list. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream", }] } ``` 1. Set the `contentHandling` property on the `Integration` resource to `CONVERT_TO_BINARY`. Do not define a mapping template. If you don't define a mapping template, API Gateway invokes the passthrough template to return the base64-decoded binary blob as the image file to the client. ``` PATCH /restapis//resources//methods//integration/responses/ { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" } ] } ``` ## Pass through a binary payload To store an image in an Amazon S3 bucket using API Gateway, do the following: 1. Update the API's `binaryMediaTypes` list by adding the binary media type of `application/octet-stream`, if it isn't already in the list. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] } ``` 1. On the `contentHandling` property of the `Integration` resource, set `CONVERT_TO_BINARY`. Set `WHEN_NO_MATCH` as the `passthroughBehavior` property value without defining a mapping template. This enables API Gateway to invoke the passthrough template. ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }, { "op" : "replace", "path" : "/passthroughBehaviors", "value" : "WHEN_NO_MATCH" } ] } ``` # Import and export content encodings for API Gateway To import the `binaryMediaTypes` list on a [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), use the following API Gateway extension to the API's OpenAPI definition file. The extension is also used to export the API settings. + [x-amazon-apigateway-binary-media-types property](api-gateway-swagger-extensions-binary-media-types.md) To import and export the `contentHandling` property value on an `Integration` or `IntegrationResponse` resource, use the following API Gateway extensions to the OpenAPI definitions: + [x-amazon-apigateway-integration object](api-gateway-swagger-extensions-integration.md) + [x-amazon-apigateway-integration.response object](api-gateway-swagger-extensions-integration-response.md) # Return binary media from a Lambda proxy integration in API Gateway To return binary media from an [AWS Lambda proxy integration](set-up-lambda-proxy-integrations.md), base64 encode the response from your Lambda function. You must also [configure your API's binary media types](api-gateway-payload-encodings-configure-with-console.md). When you configure your API's binary media types, your API treats that content type as binary data. The payload size limit is 10 MB. **Note** To use a web browser to invoke an API with this example integration, set your API's binary media types to `*/*`. API Gateway uses the first `Accept` header from clients to determine if a response should return binary media. To return binary media when you can't control the order of `Accept` header values, such as requests from a browser, set your API's binary media types to `*/*` (for all content types). The following example Lambda function can return a binary image from Amazon S3 or text to clients. The function's response includes a `Content-Type` header to indicate to the client the type of data that it returns. The function conditionally sets the `isBase64Encoded` property in its response, depending on the type of data that it returns. ------ #### [ Node.js ] ``` import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3" const client = new S3Client({region: 'us-east-2'}); export const handler = async (event) => { var randomint = function(max) { return Math.floor(Math.random() * max); } var number = randomint(2); if (number == 1){ const input = { "Bucket" : "bucket-name", "Key" : "image.png" } try { const command = new GetObjectCommand(input) const response = await client.send(command); var str = await response.Body.transformToByteArray(); } catch (err) { console.error(err); } const base64body = Buffer.from(str).toString('base64'); return { 'headers': { "Content-Type": "image/png" }, 'statusCode': 200, 'body': base64body, 'isBase64Encoded': true } } else { return { 'headers': { "Content-Type": "text/html" }, 'statusCode': 200, 'body': "

This is text

", } } } ``` ------ #### [ Python ] ``` import base64 import boto3 import json import random s3 = boto3.client('s3') def lambda_handler(event, context): number = random.randint(0,1) if number == 1: response = s3.get_object( Bucket='bucket-name', Key='image.png', ) image = response['Body'].read() return { 'headers': { "Content-Type": "image/png" }, 'statusCode': 200, 'body': base64.b64encode(image).decode('utf-8'), 'isBase64Encoded': True } else: return { 'headers': { "Content-type": "text/html" }, 'statusCode': 200, 'body': "

This is text

", } ``` ------ To learn more about binary media types, see [Binary media types for REST APIs in API Gateway](api-gateway-payload-encodings.md). # Access binary files in Amazon S3 through an API Gateway API The following examples show the OpenAPI file used to access images in Amazon S3, how to download an image from Amazon S3, and how to upload an image to Amazon S3. **Topics** + [ ## OpenAPI file of a sample API to access images in Amazon S3 ](#api-gateway-content-encodings-example-image-s3-swagger-file) + [ ## Download an image from Amazon S3 ](#api-gateway-content-encodings-example-download-image-from-s3) + [ ## Upload an image to Amazon S3 ](#api-gateway-content-encodings-example-upload-image-to-s3) ## OpenAPI file of a sample API to access images in Amazon S3 The following OpenAPI file shows a sample API that illustrates downloading an image file from Amazon S3 and uploading an image file to Amazon S3. This API exposes the `GET /s3?key={file-name}` and `PUT /s3?key={file-name}` methods for downloading and uploading a specified image file. The `GET` method returns the image file as a base64-encoded string as part of a JSON output, following the supplied mapping template, in a 200 OK response. The `PUT` method takes a raw binary blob as input and returns a 200 OK response with an empty payload. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "paths": { "/s3": { "get": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws", "contentHandling": "CONVERT_TO_BINARY" } } } }, "x-amazon-apigateway-binary-media-types": [ "application/octet-stream", "image/jpeg" ], "servers": [ { "url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "host": "abcdefghi.execute-api.us-east-1.amazonaws.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/s3": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "produces": [ "application/json", "application/octet-stream" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws", "contentHandling" : "CONVERT_TO_BINARY" } } } }, "x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"], "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Download an image from Amazon S3 To download an image file (`image.jpg`) as a binary blob from Amazon S3: ``` GET /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/octet-stream ``` The successful response looks like this: ``` 200 OK HTTP/1.1 [raw bytes] ``` The raw bytes are returned because the `Accept` header is set to a binary media type of `application/octet-stream` and binary support is enabled for the API. Alternatively, to download an image file (`image.jpg`) as a base64-encoded string (formatted as a JSON property) from Amazon S3, add a response template to the 200 integration response, as shown in the following bold-faced OpenAPI definition block: ``` "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } }, ``` The request to download the image file looks like the following: ``` GET /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json ``` The successful response looks like the following: ``` 200 OK HTTP/1.1 { "image": "W3JhdyBieXRlc10=" } ``` ## Upload an image to Amazon S3 To upload an image file (`image.jpg`) as a binary blob to Amazon S3: ``` PUT /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/octet-stream Accept: application/json [raw bytes] ``` The successful response looks like the following: ``` 200 OK HTTP/1.1 ``` To upload an image file (`image.jpg`) as a base64-encoded string to Amazon S3: ``` PUT /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json W3JhdyBieXRlc10= ``` The input payload must be a base64-encoded string because the `Content-Type` header value is set to `application/json`. The successful response looks like the following: ``` 200 OK HTTP/1.1 ``` # Access binary files in Lambda using an API Gateway API The following OpenAPI example demonstrates how to access a binary file in AWS Lambda through an API Gateway API. This API exposes the `GET /lambda?key={file-name}` and the `PUT /lambda?key={file-name}` methods for downloading and uploading a specified image file. The `GET` method returns the image file as a base64-encoded string as part of a JSON output, following the supplied mapping template, in a 200 OK response. The `PUT` method takes a raw binary blob as input and returns a 200 OK response with an empty payload. You create the Lambda function that your API calls, and it must return a base64-encoded string with the `Content-Type` header of `application/json`. **Topics** + [ ## OpenAPI file of a sample API to access images in Lambda ](#api-gateway-content-encodings-example-image-lambda-swagger-file) + [ ## Download an image from Lambda ](#api-gateway-content-encodings-example-download-image-from-lambda) + [ ## Upload an image to Lambda ](#api-gateway-content-encodings-example-upload-image-to-lambda) ## OpenAPI file of a sample API to access images in Lambda The following OpenAPI file shows an example API that illustrates downloading an image file from Lambda and uploading an image file to Lambda. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "paths": { "/lambda": { "get": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } } } }, "put": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } } } } } }, "x-amazon-apigateway-binary-media-types": [ "application/octet-stream", "image/jpeg" ], "servers": [ { "url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "host": "abcdefghi.execute-api.us-east-1.amazonaws.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/lambda": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } } } }, "put": { "produces": [ "application/json", "application/octet-stream" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "contentHandling" : "CONVERT_TO_TEXT", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } } } } } }, "x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"], "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Download an image from Lambda To download an image file (`image.jpg`) as a binary blob from Lambda: ``` GET /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/octet-stream ``` The successful response looks like the following: ``` 200 OK HTTP/1.1 [raw bytes] ``` To download an image file (`image.jpg`) as a base64-encoded string (formatted as a JSON property) from Lambda: ``` GET /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json ``` The successful response looks like the following: ``` 200 OK HTTP/1.1 { "image": "W3JhdyBieXRlc10=" } ``` ## Upload an image to Lambda To upload an image file (`image.jpg`) as a binary blob to Lambda: ``` PUT /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/octet-stream Accept: application/json [raw bytes] ``` The successful response looks like the following: ``` 200 OK ``` To upload an image file (`image.jpg`) as a base64-encoded string to Lambda: ``` PUT /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json W3JhdyBieXRlc10= ``` The successful response looks like the following: ``` 200 OK ```