How to Use Request Body in AWS API Gateway

To use the request body in AWS API Gateway, enable the integration to accept the body by setting the method's requestBody and mapping it to your backend. Use Mapping Templates in the Integration Request to transform or pass the body data to your backend service.

Syntax

The request body in API Gateway is accessed and passed using Integration Request settings. You define a Mapping Template that reads the incoming body and forwards it to your backend.

Key parts:

• Method Request: Defines if the method accepts a body.
• Integration Request: Contains the mapping template to transform the body.
• Mapping Template: Uses Velocity Template Language (VTL) to access $input.body.

plaintext

POST /resource
  Method Request:
    - Request Body: enabled
  Integration Request:
    - Mapping Template (application/json):
      {
        "body": $input.json('$')
      }

Example

This example shows how to configure a POST method in API Gateway to accept a JSON request body and forward it to a Lambda function.

json

{
  "swagger": "2.0",
  "paths": {
    "/example": {
      "post": {
        "consumes": ["application/json"],
        "produces": ["application/json"],
        "parameters": [
          {
            "in": "body",
            "name": "payload",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "message": {"type": "string"}
              }
            }
          }
        ],
        "x-amazon-apigateway-integration": {
          "type": "aws_proxy",
          "httpMethod": "POST",
          "uri": "arn:aws:apigateway:region:lambda:path/2015-03-31/functions/arn:aws:lambda:region:account-id:function:MyFunction/invocations",
          "passthroughBehavior": "when_no_match",
          "contentHandling": "CONVERT_TO_TEXT"
        }
      }
    }
  }
}

Output

When a POST request with JSON body {"message": "Hello"} is sent to /example, API Gateway forwards the body to the Lambda function as-is.

Common Pitfalls

• Not enabling request body in Method Request causes the body to be ignored.
• Missing or incorrect Mapping Template leads to empty or malformed data sent to backend.
• Using aws_proxy integration automatically passes the body, so custom mapping is unnecessary.
• For non-proxy integrations, always define mapping templates for the content type.

json

Wrong way (no mapping template):
{
  "x-amazon-apigateway-integration": {
    "type": "aws",
    "uri": "backend-uri",
    "httpMethod": "POST"
  }
}

Right way (with mapping template):
{
  "x-amazon-apigateway-integration": {
    "type": "aws",
    "uri": "backend-uri",
    "httpMethod": "POST",
    "requestTemplates": {
      "application/json": "{\"body\": $input.json('$')}"
    }
  }
}

Quick Reference

Step	Description
Enable request body	In Method Request, allow body for the HTTP method.
Set content type	Define supported content types like application/json.
Create mapping template	Use VTL to map $input.body to backend format.
Test with payload	Send a request with body and verify backend receives it.

Key Takeaways

Enable request body support in Method Request to accept data.

Use mapping templates in Integration Request to pass or transform the body.

AWS_PROXY integration passes the body automatically without mapping templates.

Always specify content types to handle different request bodies correctly.

Test your API with real payloads to ensure the body is forwarded properly.