Amazon API Gateway: Building REST APIs

Diana wrote her first Lambda function in fifteen minutes. Getting it to respond to an HTTP request from the public internet took the rest of the day. The service standing between her function and the internet was Amazon API Gateway.

This chapter is about what API Gateway does, how REST APIs work in it, and the pieces you'll touch on every project.

What API Gateway Is

API Gateway is a fully managed service that lets you create, publish, secure, and monitor APIs. It's the front door for most serverless apps — clients talk to API Gateway, API Gateway talks to your Lambda or other backends.

What you get out of the box:

• TLS termination — every endpoint is HTTPS;
• Request validation, transformation, and routing;
• Authentication via multiple mechanisms;
• Throttling and rate limiting per client;
• CloudWatch logs and metrics for every call;
• The ability to deploy multiple stages (dev, staging, prod) of the same API.

The Pieces of a REST API

A REST API in API Gateway has a clear hierarchy:

• An API is the top-level container — one API per public surface;

• An API contains Resources — paths like /users or /orders/{orderId};

• Each Resource supports one or more Methods — GET, POST, PUT, DELETE, OPTIONS;

• Each Method has an Integration — what API Gateway does when the method is called. A request flows through four steps:

• Method Request — auth, validation, parameter extraction;

• Integration Request — transform the request for the backend;

• Integration — call the backend (Lambda, HTTP endpoint, AWS service);

• Integration Response → Method Response — transform the result for the client. The two transformations in the middle are where most API Gateway features live.

Integration Types

API Gateway supports five integration types:

• Lambda proxy — passes the raw request to Lambda, expects a specific response shape back. The default for serverless;
• Lambda non-proxy (custom) — transforms request and response with mapping templates. More work, more control;
• HTTP — forward the request to any HTTP endpoint;
• AWS service — call an AWS service directly without Lambda (e.g., put a message on SQS);
• Mock — return a canned response without calling anything. Useful for development. The Lambda proxy integration is the workhorse. Diana's first API used it — point a path at a Lambda, done.

Deploying to a Stage

An API does not go live until you deploy it to a stage. A stage is a named snapshot of the API — typically dev, staging, prod. Each stage gets its own URL:

https://abc123.execute-api.us-east-1.amazonaws.com/prod

Important consequences:

• You can run multiple stages in parallel — fix a bug in dev while prod runs the old version;
• Changes to the API do not take effect until you deploy them to a stage;
• Each stage has its own throttling, logging, and caching settings.

Stage Variables

A stage variable is like an environment variable for an API stage. Common use:

• prod stage has variable lambdaAlias = prod;
• dev stage has variable lambdaAlias = dev;
• The integration uses ${stageVariables.lambdaAlias} to call the right Lambda. One API definition, multiple stages, each pointing at different backends. Clean.

Mapping Templates

For non-proxy integrations, mapping templates let you transform the request and response using Velocity Template Language (VTL). A common use is converting JSON from one shape to another, or extracting a header value into the request body.

These are powerful but ugly — most teams avoid them by using Lambda proxy integration and doing transformations in code. Know they exist for the exam.

CORS

If a browser at app.acme.com tries to call your API at api.acme.com, the browser blocks it by default — that's CORS (Cross-Origin Resource Sharing). API Gateway has an "Enable CORS" button in the Console that adds the right OPTIONS method and response headers.

Skipping CORS is the most common reason "my Lambda works in tests but my frontend cannot reach it."

What's Next

This was the foundation. The next chapter covers what makes API Gateway production-grade — authorizers, stages, throttling, and custom domains. Then we will compare REST APIs to the lighter-weight HTTP APIs.