docs: clarify that BinaryMediaTypes also affects request payloads

[roger-zhangg]

Issue #, if available

Relates to #3794

Description of changes

The BinaryMediaTypes description currently reads:

List of MIME types that your API could return. Use this to enable binary support for APIs.

"could return" 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 is what led to #3794 — a customer added BinaryMediaTypes: ["application/json"], found their request bodies base64-encoded, and reasonably filed it as a suspected SAM bug. SAM only passes the property through to the AWS::ApiGateway::RestApi resource and to x-amazon-apigateway-binary-media-types in the OpenAPI document (samtranslator/swagger/swagger.py:add_binary_media_types), so there is no request/response asymmetry SAM could introduce. The behaviour is API Gateway's; the defect is the documentation.

New text:

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.

Docs-only — no transform behaviour changes.

Description of how you validated changes

• Edited sam-docs.json and regenerated the schemas with make schema; confirmed the make lint staleness check (diff -u against a fresh generation) passes for both schema_source/sam.schema.json and samtranslator/schema/schema.json.
• The text appears twice in each generated schema because BinaryMediaTypes is declared on both AWS::Serverless::Api Properties (aws_serverless_api.py:280) and Globals (:393), which share the sam-resource-api docs stem. Verified both picked up the new wording.
• tests/schema + tests/translator pass (2928 tests). No test asserted the old string.
• Diff is minimal: 1 line in sam-docs.json, 2 lines in each generated schema.

Checklist

• Review the generative AI contribution guidelines
• Adheres to the development guidelines
• Add/update transform tests — n/a, documentation string only
  • Using correct values
  • Using wrong values
• Add/update integration tests — n/a

Note: this fixes the schema/IDE tooltip text that lives in this repo. If the published developer guide page is authored separately rather than built from sam-docs.json, a parallel docs-team change will be needed for the website to match — happy to be pointed at the right place if so.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[aws-sam-tooling-bot]

Code Review Results

Reviewed: f65ff54..66d9b01
Files: 3
Comments: 1

[aws-sam-tooling-bot]

[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.