Request and Response Mapping
You'll learn how API Gateways transform data between clients and backend services using mapping templates.
What Is Request and Response Mapping?
When a client sends a request to your API, it might not match the exact format your backend expects. Similarly, your backend's response might need reshaping before reaching the client. Request and response mapping lets you transform data structures, headers, and parameters as they flow through your API Gateway.
Think of it like a translator at a business meeting: the client speaks one language (maybe JSON with certain field names), your backend speaks another (perhaps expecting XML or different parameter names), and the API Gateway translates between them in real-time.
Core Transformation Capabilities
Request Mapping modifies incoming data before it reaches your backend:
- Rename or restructure JSON fields
- Extract query parameters and place them in the request body
- Add default values or computed fields
- Convert data formats (JSON to XML, for example)
Response Mapping transforms what comes back from your backend:
- Filter out sensitive fields before returning to clients
- Reformat error messages into a standard structure
- Add metadata like timestamps or request IDs
- Modify status codes based on response content
Mapping Templates
Most API Gateways use mapping templates written in templating languages (like Velocity Template Language in AWS). These templates define transformation rules:
Input: {"userName": "alice"}
Template rule: map "userName" → "user_name"
Output: {"user_name": "alice"}
This happens automatically for every request without changing your backend code.
Key Takeaway: Request and response mapping lets your API Gateway act as a data transformation layer, ensuring clients and backends can communicate even when they speak different formats—keeping both sides loosely coupled and easier to evolve independently.