API Gateway doesn’t just pass JSON around; it’s a full-fledged HTTP proxy that can handle any content type, including raw binary data.
Let’s see it in action. Imagine we have a backend service that accepts image uploads and returns a resized version.
# Upload a small image file
curl -X POST \
http://localhost:8080/images \
-H 'Content-Type: image/jpeg' \
--data-binary @my_image.jpg
# Expected response: a resized image
This curl command sends a JPEG image directly to the API Gateway. The gateway, in turn, forwards this binary payload to the backend service without any modification. The backend processes it and sends back a binary image, which the gateway then relays to the client.
The core problem API Gateway solves here is decoupling clients from the complexities of backend service communication. Instead of clients needing to know the direct address and protocol of every microservice, they interact with a single, consistent API endpoint. For binary data, this means the gateway acts as a transparent pipe, preserving the integrity of the payload from client to service and back.
Internally, API Gateway handles binary payloads by treating the request and response bodies as raw byte streams. When a request arrives, the gateway inspects the Content-Type header. If it’s a recognized binary type (like image/jpeg, application/octet-stream, etc.), the gateway simply streams the body data to the configured backend integration. It doesn’t attempt to parse or transform it. The same happens in reverse for the response.
The primary lever you control is the backend integration configuration. For HTTP integrations, you specify the endpoint. For Lambda integrations, the payload format version is crucial.
// Example API Gateway Integration config snippet
{
"IntegrationType": "HTTP_PROXY",
"IntegrationHttpMethod": "POST",
"IntegrationUri": "http://my-image-processing-service.internal/upload",
"ContentHandling": "PASSTHROUGH" // This is the key for binary
}
The ContentHandling property, set to PASSTHROUGH, is what tells API Gateway to forward the payload as-is. If it were CONVERT_TO_BINARY, API Gateway would attempt to convert non-binary payloads to binary, which is not what we want for raw uploads.
When using Lambda integrations, you need to ensure your Lambda function is configured to handle binary data correctly. This involves setting the Content-Type header in your Lambda function’s response and, importantly, configuring API Gateway’s integration request to specify which binary media types it should expect from the backend.
// API Gateway integration response configuration for Lambda
{
"ContentHandling": "PASSTHROUGH",
"Type": "HTTP_PROXY",
"IntegrationResponse": {
"ContentHandling": "PASSTHROUGH",
"ResponseParameters": {
"integration.response.header.Content-Type": "method.response.header.Content-Type"
},
"ResponseTemplates": {},
"StatusCode": "200"
},
"RequestParameters": {},
"RequestTemplates": {},
"Uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:my-image-processor/invocations"
}
And in your API Gateway’s REST API settings, you’d define the binary media types:
// API Gateway binary media types configuration
{
"binaryMediaTypes": [
"image/jpeg",
"image/png",
"application/octet-stream"
]
}
This tells API Gateway that if it receives a response from the backend with one of these Content-Type headers, it should treat the body as binary and not attempt any text-based transformations.
One subtle point often missed is how API Gateway handles requests where the Content-Type header is missing but the body is clearly binary. In such cases, API Gateway might default to treating it as JSON, leading to unexpected parsing errors on the backend. Always ensure your clients send a Content-Type header that accurately reflects the binary payload.
The next hurdle you’ll encounter is managing large binary payloads, which brings caching and streaming considerations into play.