Request and response mapping in AWS - Step-by-Step Execution

Process Flow - Request and response mapping

Client sends request

↓

API Gateway receives request

↓

Request Mapping Template applies

↓

Mapped request sent to backend

↓

Backend processes request

↓

Backend sends response

↓

Response Mapping Template applies

↓

Mapped response sent to client

The client sends a request that API Gateway receives. It applies a request mapping template to transform the request before sending it to the backend. After the backend processes it and sends a response, API Gateway applies a response mapping template to transform the response before sending it back to the client.

Execution Sample

AWS

POST /items HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"name":"apple","qty":10}

Client sends a POST request with JSON data to API Gateway, which will map the request and response.

Process Table

Step	Action	Input	Output	Notes
1	Receive client request	{"name":"apple","qty":10}	Raw request data	API Gateway gets the original request
2	Apply request mapping	Raw request data	{"itemName":"apple","quantity":10}	Transforms JSON keys to backend format
3	Send mapped request to backend	{"itemName":"apple","quantity":10}	Mapped request sent	Backend receives transformed data
4	Backend processes request	{"itemName":"apple","quantity":10}	{"status":"success","id":123}	Backend creates item and returns response
5	Apply response mapping	{"status":"success","id":123}	{"result":"Item created","itemId":123}	Transforms backend response to client format
6	Send mapped response to client	{"result":"Item created","itemId":123}	Final response to client	Client receives transformed response
7	End	N/A	N/A	Request-response cycle complete

💡 Request and response mapping complete; client receives final transformed response.

Status Tracker

Variable	Start	After Step 2	After Step 4	After Step 5	Final
RequestPayload	{"name":"apple","qty":10}	{"itemName":"apple","quantity":10}	{"itemName":"apple","quantity":10}	{"itemName":"apple","quantity":10}	Sent to backend
ResponsePayload	N/A	N/A	{"status":"success","id":123}	{"result":"Item created","itemId":123}	Sent to client

Key Moments - 3 Insights

Why do we need to transform the request before sending it to the backend?

Because the backend expects data in a specific format different from the client’s. The request mapping template changes the client’s data to match backend requirements, as shown in step 2 of the execution_table.

What happens if the response mapping template is missing or incorrect?

The client might receive data in an unexpected format, causing confusion or errors. Step 5 shows how the response is transformed to the client’s expected format.

Does the original client request get changed?

No, the original request stays the same. API Gateway creates a transformed copy for the backend, as seen in variable_tracker where RequestPayload changes after step 2 but original client data is preserved.

Visual Quiz - 3 Questions

Look at the execution_table, what is the output after applying the request mapping template (Step 2)?

A {"name":"apple","qty":10}

B {"itemName":"apple","quantity":10}

C {"status":"success","id":123}

D {"result":"Item created","itemId":123}

💡 Hint

Check the Output column at Step 2 in the execution_table.

At which step does the backend send its response?

A Step 3

B Step 5

C Step 4

D Step 6

💡 Hint

Look for the step where backend processes and returns data in the execution_table.

If the response mapping template was removed, what would the client receive?

A The backend response without transformation

B The original client request

C An error message from API Gateway

D An empty response

💡 Hint

Refer to the role of response mapping in Step 5 and 6 in the execution_table.

Concept Snapshot

Request and response mapping in API Gateway:
- Client sends request
- Request mapping template transforms request
- Backend receives transformed request
- Backend sends response
- Response mapping template transforms response
- Client receives transformed response
Mapping ensures backend and client understand each other.

Full Transcript

In request and response mapping, the client sends a request to API Gateway. API Gateway applies a request mapping template to change the request format to what the backend expects. The backend processes this transformed request and sends back a response. API Gateway then applies a response mapping template to change the backend response into a format the client expects. Finally, the client receives this transformed response. This process ensures smooth communication between client and backend even if they use different data formats.

Practice

1. What is the main purpose of request and response mapping in AWS API Gateway?

easy

A. To encrypt data during transmission

B. To change data formats between client and backend

C. To monitor user activity on the website

D. To store data permanently in the cloud

Solution

1. Step 1: Understand the role of mapping templates

   Mapping templates in API Gateway transform data formats between client requests and backend responses.

2. Step 2: Identify the main purpose

   This transformation allows different systems to communicate smoothly by renaming, adding, or removing fields.

3. Final Answer:

   To change data formats between client and backend -> Option B

4. Quick Check:

   Mapping templates = data format change [OK]

Hint: Mapping templates transform data formats between client and backend [OK]

Common Mistakes:

• Confusing mapping with data storage
• Thinking mapping encrypts data
• Assuming mapping monitors activity

2. Which of the following is the correct syntax to access a JSON field named userId in a request mapping template?

easy

A. $input.path('$.userId')

B. $input.json('userId')

C. $input.get('userId')

D. $input.body('userId')

Solution

1. Step 1: Recall JSON path syntax in mapping templates

   The correct way to access a JSON field is using $input.path('$.fieldName').

2. Step 2: Match the syntax to the field userId

   Using $input.path('$.userId') correctly accesses the userId field.

3. Final Answer:

   $input.path('$.userId') -> Option A

4. Quick Check:

   JSON field access = $input.path('$.field') [OK]

Hint: Use $input.path('$.fieldName') to access JSON fields [OK]

Common Mistakes:

• Using incorrect method names like json or get
• Missing the '$.' prefix in JSON path
• Confusing body access with path access

3. Given this request mapping template:

{
  "user": "$input.path('$.username')",
  "id": "$input.path('$.userId')"
}

What will be the transformed request if the client sends:

{"username": "alice", "userId": "123"}

medium

A. {"user": "$.username", "id": "$.userId"}

B. {"username": "alice", "userId": "123"}

C. {"user": "alice", "id": "123"}

D. {"user": null, "id": null}

Solution

1. Step 1: Understand the mapping template fields

   The template maps user to $.username and id to $.userId.

2. Step 2: Apply the client JSON values

   Client sends username as "alice" and userId as "123", so these replace the template placeholders.

3. Final Answer:

   {"user": "alice", "id": "123"} -> Option C

4. Quick Check:

   Template fields replaced by client values [OK]

Hint: Mapping replaces template fields with client JSON values [OK]

Common Mistakes:

• Confusing template keys with client keys
• Leaving placeholders as literal strings
• Assuming null values when fields exist

4. You have this response mapping template:

{
  "message": "$input.path('$.msg')",
  "status": "$input.path('$.code')"
}

But the backend returns:

{"message": "Success", "code": 200}

What is the main issue causing the mapping to fail?

medium

A. The template uses wrong JSON paths not matching backend keys

B. The backend response is not valid JSON

C. The template syntax is missing quotes around keys

D. The backend response keys are case-insensitive

Solution

1. Step 1: Compare template paths with backend keys

   The template expects msg and code, but backend returns message and code.

2. Step 2: Identify mismatch causing failure

   Since msg does not exist in backend response, mapping fails for that field.

3. Final Answer:

   The template uses wrong JSON paths not matching backend keys -> Option A

4. Quick Check:

   Template paths must match backend keys exactly [OK]

Hint: Ensure template JSON paths match backend response keys exactly [OK]

Common Mistakes:

• Assuming backend keys are case-insensitive
• Thinking syntax errors cause this issue
• Ignoring key name mismatches

5. You want to add a new field requestTime with the current timestamp to every request sent to your backend using request mapping. Which mapping template snippet correctly adds this field?

hard

A. {
"user": "$input.path('$.user')",
"requestTime": "$context.stage"
}

B. {
"user": "$input.path('$.user')",
"requestTime": "$input.requestTime"
}

C. {
"user": "$input.path('$.user')",
"requestTime": "$stageVariables.requestTime"
}

D. {
"user": "$input.path('$.user')",
"requestTime": "$context.requestTime"
}

Solution

1. Step 1: Identify how to get current request time

   In API Gateway mapping templates, $context.requestTime provides the current request timestamp.

2. Step 2: Check each option for correct usage

   { "user": "$input.path('$.user')", "requestTime": "$context.requestTime" } uses $context.requestTime correctly; others use invalid or unrelated variables.

3. Final Answer:

   { "user": "$input.path('$.user')", "requestTime": "$context.requestTime" } -> Option D

4. Quick Check:

   Use $context.requestTime for current timestamp [OK]

Hint: Use $context.requestTime to add current timestamp in mapping [OK]

Common Mistakes:

• Using $input.requestTime which doesn't exist
• Confusing stage variables with request time
• Using unrelated context variables