Request and response mapping in AWS - Commands & Configuration

Introduction

When you create an API with AWS API Gateway, you often need to change the shape of the data that comes in or goes out. Request and response mapping lets you change the data format so your backend and frontend can talk smoothly, even if they expect different formats.

When your frontend sends data in a format your backend does not understand.

When your backend returns data that needs to be simplified or changed before sending to the user.

When you want to add or remove fields from the data without changing your backend code.

When you want to convert data formats, like from JSON to XML or vice versa.

When you want to log or audit the data passing through your API.

Config File - api-gateway-mapping-template.vtl

api-gateway-mapping-template.vtl

# Request mapping template example
{
  "userId": "$input.path('$.user.id')",
  "action": "$input.path('$.action')"
}

# Response mapping template example
{
  "status": "$input.path('$.status')",
  "message": "$input.path('$.message')"
}

This file contains two Velocity Template Language (VTL) templates used by AWS API Gateway.

The first part is the request mapping template. It extracts the user ID and action from the incoming JSON and creates a new JSON with just those fields to send to the backend.

The second part is the response mapping template. It takes the backend response and extracts the status and message fields to send back to the client.

Commands

Create a new REST API named 'example-api' in AWS API Gateway.

Terminal

aws apigateway create-rest-api --name example-api

Expected Output

{

    "id": "a1b2c3d4e5",

    "name": "example-api",

    "createdDate": "2024-06-01T12:00:00Z",

    "endpointConfiguration": {

        "types": ["REGIONAL"]

    }

}

→

--name - Sets the name of the new API

Set up the integration between the API Gateway POST method and a Lambda function, using the request mapping template to transform incoming data.

Terminal

aws apigateway put-integration --rest-api-id a1b2c3d4e5 --resource-id r1a2b3c4 --http-method POST --type AWS_PROXY --integration-http-method POST --uri arn:aws:lambda:us-east-1:123456789012:function:my-function --request-templates file://api-gateway-mapping-template.vtl

Expected Output

{

    "type": "AWS_PROXY",

    "httpMethod": "POST",

    "uri": "arn:aws:lambda:us-east-1:123456789012:function:my-function",

    "requestTemplates": {

        "application/json": "# Request mapping template example\n{\n  \"userId\": \"$input.path('$.user.id')\",\n  \"action\": \"$input.path('$.action')\"\n}\n"

    }

}

→

--rest-api-id - Specifies the API to configure

→

--resource-id - Specifies the resource within the API

→

--request-templates - Points to the file with the request mapping template

Define the method response for HTTP 200 status with an empty model, preparing for response mapping.

Terminal

aws apigateway put-method-response --rest-api-id a1b2c3d4e5 --resource-id r1a2b3c4 --http-method POST --status-code 200 --response-models application/json=Empty

Expected Output

{}

→

--status-code - Sets the HTTP status code for the response

Set the response mapping template to transform the backend response before sending it to the client.

Terminal

aws apigateway put-integration-response --rest-api-id a1b2c3d4e5 --resource-id r1a2b3c4 --http-method POST --status-code 200 --response-templates application/json=file://api-gateway-mapping-template.vtl

Expected Output

{}

→

--response-templates - Points to the file with the response mapping template

Test the API method with a sample request body to see how the request and response mapping works.

Terminal

aws apigateway test-invoke-method --rest-api-id a1b2c3d4e5 --resource-id r1a2b3c4 --http-method POST --body '{"user":{"id":"123"},"action":"login"}'

Expected Output

{

    "status": 200,

    "body": "{\"status\":\"success\",\"message\":\"User logged in\"}"

}

Key Concept

If you remember nothing else from this pattern, remember: request and response mapping lets you change data formats between your API and backend without changing backend code.

Common Mistakes

Not specifying the correct content type in the mapping templates.

API Gateway won't apply the mapping templates if the content type doesn't match, causing data to pass through unchanged or errors.

Always use the correct content type like 'application/json' in your request and response mapping configurations.

Using incorrect JSON path expressions in the mapping templates.

Wrong paths cause missing or wrong data to be sent to the backend or returned to the client.

Test your JSON paths carefully and use tools or logs to verify they extract the right data.

Forgetting to deploy the API after changes.

Changes to mapping templates won't take effect until the API is deployed, so you won't see your updates.

Always deploy your API after making changes to mapping templates.

Summary

Create an API Gateway REST API and define resources and methods.

Use request mapping templates to change incoming data before it reaches your backend.

Use response mapping templates to change backend responses before sending to clients.

Test your API to ensure mappings work as expected.