0Pricing
Serverless Backend with AWS Lambda & API Gateway · Lesson

Request/Response Transformations

Customize API Gateway's request and response payloads using mapping templates (VTL) to integrate with diverse backend systems.

Request/Response Transformations is a free Serverless Backend with AWS Lambda & API Gateway lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Serverless Backend with AWS Lambda & API Gateway learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Bridging the Data Gap

Imagine your API clients speak one data language, but your backend service understands another. How do you make them communicate smoothly?

API Gateway's request and response transformations act as a universal translator, modifying payloads to ensure compatibility between different systems.

Introducing Mapping Templates

At the heart of transformations are mapping templates. These are text-based templates written using the Velocity Template Language (VTL).

You define a VTL template that tells API Gateway exactly how to restructure or modify the incoming (request) or outgoing (response) data.

Request Transformations

Request transformations modify the data sent by your client before it reaches your backend service (like a Lambda function).

This is useful for:

  • Simplifying complex client requests for a backend.
  • Adding specific headers or parameters.
  • Converting data formats (e.g., XML to JSON, or a different JSON structure).

VTL for Request Mapping

Here's a simple VTL example for a request. It takes a client's id and qty and maps them to productId and quantity for your backend.

The $input variable gives you access to the incoming request body and parameters.

#set($body = $input.json('$'))
{
  "productId": "$body.id",
  "quantity": $body.qty
}

Accessing Request Context

Besides the body, you can access other request details like path parameters, query strings, and headers using the $context variable.

This allows you to enrich your backend's input with valuable contextual information from the API call.

#set($body = $input.json('$'))
{
  "userId": "$context.authorizer.claims.sub",
  "resourcePath": "$context.resourcePath",
  "itemId": "$input.params('itemId')",
  "requestedQuantity": $body.qty
}

Response Transformations

Response transformations modify the data returned by your backend service before it's sent back to the client.

This is crucial for:

  • Standardizing API responses across different backends.
  • Masking sensitive internal details from clients.
  • Converting backend output to a client-friendly format.

VTL for Response Mapping

Similar to requests, you use VTL to transform responses. Here, a backend's result field is mapped to a more generic data field for the client.

The $input variable in a response template refers to the backend's output.

#set($body = $input.json('$'))
{
  "status": "success",
  "data": $body.result
}

Conditional Response Mapping

API Gateway allows you to define different response templates based on the backend's HTTP status code. This means you can have a specific template for success (e.g., 200 OK) and another for errors (e.g., 400 Bad Request).

This provides granular control over how different outcomes are presented to the client.

#if($input.path('$.statusCode') == 200)
{
  "message": "Operation successful."
}
#else
{
  "error": "$input.path('$.errorMessage')"
}
#end

VTL Best Practices

When writing VTL templates:

  • Keep it simple: Avoid complex logic; delegate to your backend if needed.
  • Test thoroughly: Use API Gateway's test invocation feature.
  • Use $util.urlEncode: Encode values when placing them into URLs or query strings.
  • Handle nulls: Use $!variable to output an empty string if a variable is null.

Quick Check

You've learned how API Gateway transformations can reshape data. Which of the following are key benefits of using request/response transformations?

Recap: Mastering Transformations

You've learned how API Gateway transformations, powered by VTL mapping templates, are essential for building flexible and robust APIs.

By shaping both incoming requests and outgoing responses, you can ensure seamless communication between diverse clients and backend services, improving maintainability and reducing complexity.

Frequently asked questions

Is the “Request/Response Transformations” lesson free?

Yes — the full text of “Request/Response Transformations” is free to read here on the web, and the Serverless Backend with AWS Lambda & API Gateway course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Serverless Backend with AWS Lambda & API Gateway course, upgrade to CoddyKit PRO.

What will I learn in “Request/Response Transformations”?

Customize API Gateway's request and response payloads using mapping templates (VTL) to integrate with diverse backend systems. You practise Serverless Backend with AWS Lambda & API Gateway with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Serverless Backend with AWS Lambda & API Gateway?

No prior experience is required. Serverless Backend with AWS Lambda & API Gateway on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Request/Response Transformations” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Serverless Backend with AWS Lambda & API Gateway lesson?

Yes. Every Serverless Backend with AWS Lambda & API Gateway lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Caching and Throttling
  2. Request/Response Transformations
  3. Custom Domain Names & Edge Optimization
  4. WebSocket APIs for Real-Time Communication
← Back to Serverless Backend with AWS Lambda & API Gateway