Skip to content

docs: clarify that BinaryMediaTypes also affects request payloads #3966

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
roger-zhangg wants to merge 1 commit into
base: develop
Choose a base branch
from
+5 −5
Open

docs: clarify that BinaryMediaTypes also affects request payloads #3966

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion samtranslator/internal/schema_source/sam-docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -738,7 +738,7 @@
"AlwaysDeploy": "Always deploys the API, even when no changes to the API have been detected. \n*Type*: Boolean \n*Required*: No \n*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.",
"ApiKeySourceType": "The source of the API key for metering requests according to a usage plan. Valid values are `HEADER` and `AUTHORIZER`. \n*Type*: String \n*Required*: No \n*CloudFormation compatibility*: This property is passed directly to the [`ApiKeySourceType`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-apikeysourcetype) property of an `AWS::ApiGateway::RestApi` resource.",
"Auth": "Configure authorization to control access to your API Gateway API. \nFor more information about configuring access using AWS SAM see [Control API access with your AWS SAM template](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-controlling-access-to-apis.html). For an example showing how to override a global authorizer, see [Override a global authorizer for your Amazon API Gateway REST API](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-property-function-apifunctionauth.html#sam-property-function-apifunctionauth--examples--override). \n*Type*: [ApiAuth](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-property-api-apiauth.html) \n*Required*: No \n*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.",
"BinaryMediaTypes": "List of MIME types that your API could return. Use this to enable binary support for APIs. \n*Type*: List \n*Required*: No \n*CloudFormation compatibility*: This property is similar to the [`BinaryMediaTypes`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.",
"BinaryMediaTypes": "List of MIME types that your API could return, and that it accepts in request payloads. Use this to enable binary support for APIs. This list applies to both directions: when an incoming request's `Content-Type` matches an entry, API Gateway base64-encodes the request body and sets `isBase64Encoded` to `true` on the event passed to your function. \n*Type*: List \n*Required*: No \n*CloudFormation compatibility*: This property is similar to the [`BinaryMediaTypes`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.",

@aws-sam-tooling-bot aws-sam-tooling-bot Bot Aug 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[GENERAL] The added sentence states the request-side behavior unconditionally, but base64-encoding of the request body and the isBase64Encoded flag are specific to Lambda proxy integration (AWS_PROXY). AWS::Serverless::Api also supports non-proxy Lambda integrations, HTTP/HTTP_PROXY, MOCK, and arbitrary integrations supplied through DefinitionBody — in those cases there is no Lambda event and no isBase64Encoded field, and conversion depends on the integration's contentHandling setting.

Two concrete misreadings the current wording invites:

  • "MIME types ... that it accepts in request payloads" can read as an allow-list, implying request content types absent from the list are rejected. They aren't — they're just not treated as binary.
  • "the event passed to your function" implies every API in this list is Lambda-backed with a proxy integration.

Since the point of this change is to prevent a wrong inference (the one behind #3794), it's worth scoping the claim rather than trading one ambiguity for another. Suggested wording:

List of MIME types that your API treats as binary, for both request and response payloads. Use this to enable binary support for APIs. When an incoming request's Content-Type matches an entry, API Gateway treats the body as binary; for Lambda proxy integrations this means the body is base64-encoded and isBase64Encoded is set to true on the event passed to your function. Request content types that are not in the list are still accepted, but are not treated as binary.

Note this string only needs editing here — the two occurrences in schema_source/sam.schema.json and samtranslator/schema/schema.json are regenerated from this entry by make schema.

"CacheClusterEnabled": "Indicates whether caching is enabled for the stage. To cache responses, you must also set `CachingEnabled` to `true` under `MethodSettings`. \n*Type*: Boolean \n*Required*: No \n*CloudFormation compatibility*: This property is passed directly to the [`CacheClusterEnabled`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclusterenabled) property of an `AWS::ApiGateway::Stage` resource.",
"CacheClusterSize": "The stage's cache cluster size. \n*Type*: String \n*Required*: No \n*CloudFormation compatibility*: This property is passed directly to the [`CacheClusterSize`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclustersize) property of an `AWS::ApiGateway::Stage` resource.",
"CanarySetting": "Configure a canary setting to a stage of a regular deployment. \n*Type*: [CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting) \n*Required*: No \n*CloudFormation compatibility*: This property is passed directly to the [`CanarySetting`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting) property of an `AWS::ApiGateway::Stage` resource.",
Expand Down
4 changes: 2 additions & 2 deletions samtranslator/schema/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -376517,7 +376517,7 @@
"$ref": "#/definitions/PassThroughProp"
}
],
"markdownDescription": "List of MIME types that your API could return. Use this to enable binary support for APIs. \n*Type*: List \n*Required*: No \n*CloudFormation compatibility*: This property is similar to the [`BinaryMediaTypes`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.",
"markdownDescription": "List of MIME types that your API could return, and that it accepts in request payloads. Use this to enable binary support for APIs. This list applies to both directions: when an incoming request's `Content-Type` matches an entry, API Gateway base64-encodes the request body and sets `isBase64Encoded` to `true` on the event passed to your function. \n*Type*: List \n*Required*: No \n*CloudFormation compatibility*: This property is similar to the [`BinaryMediaTypes`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.",
"title": "BinaryMediaTypes"
},
"CacheClusterEnabled": {
Expand Down Expand Up @@ -376686,7 +376686,7 @@
"$ref": "#/definitions/PassThroughProp"
}
],
"markdownDescription": "List of MIME types that your API could return. Use this to enable binary support for APIs. \n*Type*: List \n*Required*: No \n*CloudFormation compatibility*: This property is similar to the [`BinaryMediaTypes`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.",
"markdownDescription": "List of MIME types that your API could return, and that it accepts in request payloads. Use this to enable binary support for APIs. This list applies to both directions: when an incoming request's `Content-Type` matches an entry, API Gateway base64-encodes the request body and sets `isBase64Encoded` to `true` on the event passed to your function. \n*Type*: List \n*Required*: No \n*CloudFormation compatibility*: This property is similar to the [`BinaryMediaTypes`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.",
"title": "BinaryMediaTypes"
},
"CacheClusterEnabled": {
Expand Down
4 changes: 2 additions & 2 deletions schema_source/sam.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4910,7 +4910,7 @@
"$ref": "#/definitions/PassThroughProp"
}
],
"markdownDescription": "List of MIME types that your API could return. Use this to enable binary support for APIs. \n*Type*: List \n*Required*: No \n*CloudFormation compatibility*: This property is similar to the [`BinaryMediaTypes`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.",
"markdownDescription": "List of MIME types that your API could return, and that it accepts in request payloads. Use this to enable binary support for APIs. This list applies to both directions: when an incoming request's `Content-Type` matches an entry, API Gateway base64-encodes the request body and sets `isBase64Encoded` to `true` on the event passed to your function. \n*Type*: List \n*Required*: No \n*CloudFormation compatibility*: This property is similar to the [`BinaryMediaTypes`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.",
"title": "BinaryMediaTypes"
},
"CacheClusterEnabled": {
Expand Down Expand Up @@ -5227,7 +5227,7 @@
"$ref": "#/definitions/PassThroughProp"
}
],
"markdownDescription": "List of MIME types that your API could return. Use this to enable binary support for APIs. \n*Type*: List \n*Required*: No \n*CloudFormation compatibility*: This property is similar to the [`BinaryMediaTypes`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.",
"markdownDescription": "List of MIME types that your API could return, and that it accepts in request payloads. Use this to enable binary support for APIs. This list applies to both directions: when an incoming request's `Content-Type` matches an entry, API Gateway base64-encodes the request body and sets `isBase64Encoded` to `true` on the event passed to your function. \n*Type*: List \n*Required*: No \n*CloudFormation compatibility*: This property is similar to the [`BinaryMediaTypes`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.",
"title": "BinaryMediaTypes"
},
"CacheClusterEnabled": {
Expand Down