From 66d9b01e91f2d9c001ce07450546219fd493834c Mon Sep 17 00:00:00 2001 From: Roger Zhang Date: Fri, 31 Jul 2026 16:58:47 -0700 Subject: [PATCH] docs: clarify that BinaryMediaTypes also affects request payloads Reported in aws/serverless-application-model#3794. The BinaryMediaTypes description says "List of MIME types that your API could return", which reads as response-only. In practice the list applies in 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 handed to the function. That wording led a customer to file #3794 as a suspected SAM bug after adding `BinaryMediaTypes: ["application/json"]` and finding their request bodies base64-encoded. SAM only passes the property through to the RestApi resource and the OpenAPI document, so the behaviour is API Gateway's -- the defect is the documentation. Updates sam-docs.json and regenerates sam.schema.json and schema.json. The text appears twice in the generated schemas because BinaryMediaTypes is declared on both AWS::Serverless::Api Properties and Globals, which share the sam-resource-api docs stem. --- samtranslator/internal/schema_source/sam-docs.json | 2 +- samtranslator/schema/schema.json | 4 ++-- schema_source/sam.schema.json | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/samtranslator/internal/schema_source/sam-docs.json b/samtranslator/internal/schema_source/sam-docs.json index 30f81c3b8..dbb233915 100644 --- a/samtranslator/internal/schema_source/sam-docs.json +++ b/samtranslator/internal/schema_source/sam-docs.json @@ -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.", "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.", diff --git a/samtranslator/schema/schema.json b/samtranslator/schema/schema.json index abd2b0c6b..b120fe717 100644 --- a/samtranslator/schema/schema.json +++ b/samtranslator/schema/schema.json @@ -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": { @@ -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": { diff --git a/schema_source/sam.schema.json b/schema_source/sam.schema.json index 1ced46489..6274b23c0 100644 --- a/schema_source/sam.schema.json +++ b/schema_source/sam.schema.json @@ -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": { @@ -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": {