Request and Response Mapping in API Gateway

API Gateway sits between clients and your backend. Mapping lets you transform the request before it reaches the backend and the response before it returns to the client, decoupling the two.

• Reshape payloads
• Move data between path, query, headers, and body
• Translate backend errors into clean client responses

You can extract values from the request path, query string, and headers, then pass them to the backend in a different location. For example, a path parameter can become a body field.

With proxy integration, the entire request is forwarded as-is and your function parses it. With non-proxy integration, you define explicit mappings, giving more control but more configuration.

Non-proxy integrations use mapping templates to reshape the body. The template reads input fields and emits the structure the backend expects.

You can rename fields, add constants, or drop unwanted data so the backend receives exactly what it needs, regardless of how the client formatted the request.

On the way back, response mapping lets you reshape the backend output: hide internal fields, rename keys, or wrap data in an envelope before returning it to the client.

Backends may signal errors via messages while returning 200. API Gateway can map backend output to proper HTTP status codes so clients get correct semantics like 404 or 400.

Stage variables let one API definition point at different backends per stage (dev, prod) without changing the mapping, by referencing a variable in the integration target.

API Gateway can validate incoming requests against a model before invoking the backend, rejecting malformed payloads early and saving function invocations.

You can map different content types to different templates, for example handling both JSON and form-encoded bodies, or converting binary uploads appropriately.

Light reshaping belongs in the gateway to keep functions clean. Complex logic belongs in code. Proxy integration plus in-function parsing is simplest; non-proxy mapping suits stable, well-defined contracts.

Test your mapping knowledge.

You learned how API Gateway performs request and response mapping: extracting path/query/header parameters, using mapping templates in non-proxy integrations, transforming bodies, mapping status codes, leveraging stage variables, validating requests, and deciding when to map versus handle logic in code.