Enabling `BinaryMediaTypes` on `AWS::Serverless::Api` Base64-encodes request payload body

[davidjb]

Description

When enabling AWS::ApiGateway::RestApi's BinaryMediaTypes for a particular type (such as application/json), this causes the request's body to have been Base64-encoded when received, as well as the expected behaviour of allowing the API to return binary data as a Base64-encoded body within the response payload.

This is unexpected behaviour given the documentation (see below for why), or it could be a bug. Getting clarification on which it is is critical to the use of these resources in AWS; if a documentation issue, the published info should be clearly explained.

The docs on AWS::ApiGateway::RestApi's BinaryMediaTypes suggests this only affects the response (emphasis mine):

List of MIME types that your API could return. Use this to enable binary support for APIs. Use ~1 instead of / in the mime types.

AWS CloudFormation compatibility: This property is similar to the BinaryMediaTypes property of an AWS::ApiGateway::RestApi resource. The list of BinaryMediaTypes is added to both the AWS CloudFormation resource and the OpenAPI document.

The docs above appear outdated as the Use ~1 instead of / in the mime types. reference no long applies - using application/json works fine via SAM locally and when deployed to production AWS. Online resources such as this StackOverflow answer suggest confusion and suggest the AWS docs were wrong and that the AWS::ApiGateway::RestApi has since been fixed up.

On the linked AWS::ApiGateway::RestApi, the docs are unclear:

BinaryMediaTypes: The list of binary media types supported by the RestApi. By default, the RestApi supports only UTF-8-encoded text payloads.

Steps to reproduce

Resources:
  MyAPI:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      BinaryMediaTypes: ["application/json"]

Observed result

1. Deploy a SAM template such as that above, with a corresponding Lambda function
2. Observe that in an AWS Lambda function, the isBase64Encoded property on the request is true and the body is encoded with Base64.

Expected result

1. Establish if the behaviour of Base64-encoding the request payload body when BinaryMediaTypes is enabled is expected.

2. Update the documentation for https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-api.html#sam-api-binarymediatypes accordingly:

   1. Indicate that the BinaryMediaTypes option will Base64-encode the request body and require that the response body be Base64-encoded.
   2. Remove or correct the Use ~1 instead of / in the mime types. reference.

3. Update the document for https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes accordingly to indicate the same impact above.

If the behaviour is not correct, then the resolution would be to fix how SAM and AWS operate.

Additional environment details

1. OS: Ubuntu 24.04
2. If using the SAM CLI, sam --version: SAM CLI, version 1.142.1
3. AWS region: us-east-1