Amazon API GatewayAuthorCloudBrum editorial teamLast reviewed24 Oct 2026Reading time~12 minLevelBeginner to advanced

• Three kinds of APIREST APIs have the most features, HTTP APIs are leaner and cheaper, and WebSocket APIs keep a two-way connection open for chat or live dashboards.
• Many ways to check a callerIAM signatures, Amazon Cognito, JWT tokens from any OpenID Connect provider, Lambda authorizers you write yourself, and mutual TLS on a custom domain.
• Throttling out of the boxA token-bucket limit applies per Region for the account, and you can tighten it for a stage, a route or (on REST APIs) each customer through a usage plan.
• Reaches private back endsA VPC link lets the gateway call services that have no public address, such as an internal load balancer.
• Your own domainAttach a custom domain with an ACM certificate, map base paths to different APIs, and on REST APIs route by header or path with routing rules.
• Start from an OpenAPI fileImport an OpenAPI definition to create routes and models, and export one again when another tool needs it.
• Streaming responsesREST APIs with a proxy integration can stream the response as it is produced, which gets around the usual timeout and size limits for long outputs.
• Developer portalA managed portal can list your REST APIs and generate their documentation, so partners can find what they are allowed to call.

API

The set of HTTP routes you publish. In API Gateway it is also the top-level object you create, with its own ID and invoke URL.

Route and method

HTTP and WebSocket APIs use routes such as GET /orders/{id}. REST APIs build the same thing from resources and methods.

Integration

What happens when a route is called: run a Lambda function, forward to an HTTP address, call an AWS service, or return a fixed answer.

Proxy integration

API Gateway passes the whole request to the back end as it is and returns whatever the back end sends, without reshaping it.

Stage

A named, deployed copy of an API, such as dev or prod. HTTP APIs also offer a $default stage that is served from the root of the URL.

Deployment

A snapshot of a REST API’s configuration. Changes only go live after you deploy to a stage, which catches many people out.

Endpoint type

Edge-optimised (through CloudFront), Regional (served from one Region) or private (reachable only from inside your VPC, REST APIs only).

Authorizer

The check that runs before the integration. It can be IAM, a Cognito user pool, a JWT validator or a Lambda function that returns an allow or deny policy.

Usage plan and API key

A REST API feature that gives each client its own rate and quota. A key identifies the client for metering. It is not a password.

Throttling

A token-bucket limit on requests per second with a burst allowance. Over the limit, callers get HTTP 429.

Mapping template

A Velocity template on a REST API that reshapes a request or response, for example to call DynamoDB or SQS without a Lambda function in between.

VPC link

A private connection from the gateway to a load balancer or service in your VPC.

Custom domain name

Your own hostname in front of one or more APIs, with a TLS certificate from AWS Certificate Manager and base path mappings.

Payload format version

The shape of the event sent to Lambda. HTTP APIs default to version 2.0, which is flatter and smaller than the REST format.

Create an HTTP API in the AWS console

1. Open API Gateway and pick HTTP APISearch for API Gateway, choose your Region and press Build under HTTP API. If you already know you need keys or caching, pick REST API instead.
2. Add an integrationChoose Lambda and select the function. For an existing web service pick HTTP URL and paste its address.
3. Define the routesAdd the method and path you want, for example GET /orders. A catch-all route such as ANY /{proxy+} is handy early on and too loose for production.
4. Accept the default stageThe $default stage with auto-deploy means every change is live at once. Create named stages later if you want separate dev and prod copies.
5. Call itCopy the invoke URL and try it with curl. A 200 with your function’s output means the whole chain works. A 5xx usually points at the integration.
6. Add authorisationUnder Authorization create a JWT authorizer with your identity provider’s issuer URL and the app’s client ID, then attach it to the routes that need it.
7. Set CORS if a browser calls itAllow only your site’s origin and the methods and headers you use. Leaving it at * is fine for a demo and a mistake for anything real.
8. Limit the damageSet default route throttling on the stage, and decide what the right ceiling is before a bug or a bad client decides for you.
9. Switch on logs and add a domainTurn on access logging to a CloudWatch log group, add an alarm on 5xx and latency, then attach your custom domain name.

• Pick HTTP API unless a REST-only feature is truly needed. It also tends to respond a little faster, as well as costing less.
• Use payload format 2.0 with Lambda. The event is smaller and has less to parse.
• Cache what doesn’t change. REST APIs can cache responses per stage, and a short TTL is still a big win for popular GET routes.
• Put CloudFront in front when callers are spread around the world, or when responses can be cached closer to them.
• Keep authorizer work small, and cache its result. A Lambda authorizer that runs on every call adds its own Lambda bill and its own latency.
• Compare the Latency and IntegrationLatency metrics. The gap between them is the gateway’s own share, and usually the smaller one.
• Don’t make callers wait on slow jobs. Take the request, queue it, answer 202, and let the client poll or get a callback.
• Skip mapping templates for large bodies, and avoid extra hops such as a Lambda that only forwards the request to another service.

FinOps is the habit of managing cloud spend together with engineering. These are the FinOps checks that matter most for Amazon API Gateway.

• Start with an HTTP API. At the first pricing tier it costs roughly a third of a REST API per million calls.
• Don’t pay for features you don’t use. REST API caching is billed by the hour for as long as the cache exists, used or not.
• A cache hit never touches the back end, which is the whole point. Even a one-minute TTL on a hot route can take a visible bite out of Lambda and database charges.
• Watch the neighbours: Lambda, NAT gateways, CloudWatch Logs ingestion and data transfer often cost more than the gateway itself.
• Log only what you need. Full execution logging on a busy API fills CloudWatch quickly, so use access logs, a short retention and sampling.
• Reject junk early with request validation, WAF rules and throttling, so bad calls don’t reach (or bill) the back end.
• Move big downloads and uploads to S3 and CloudFront, not through the API.
• Delete test APIs and old stages. Release custom domains you no longer use.
• Tag APIs by team and product, and set a budget alert on API Gateway as a line item.
• Check the free allowance before a pilot. The first pricing tier isn’t what you’ll pay at scale, so read the page for your Region.

• Authorise every route. Prefer a JWT or Cognito authorizer for end users and IAM for AWS-to-AWS calls.
• Use API keys only to meter and throttle clients, never as the only protection.
• Attach AWS WAF to REST API stages to block common attacks and bad IP ranges. HTTP APIs can’t take a web ACL directly.
• Validate requests (schema, size, required fields) before they reach the function.
• Restrict CORS to the origins you own.
• Use private APIs with VPC endpoints and a resource policy for internal use, and mutual TLS on the custom domain when clients must present a certificate.
• Keep back ends private. Use VPC links and security groups so the only way in is through the gateway.
• Pick a current TLS security policy on custom domains and let ACM renew certificates.
• Send access logs to CloudWatch, record changes in CloudTrail, and keep tokens and personal data out of logs.
• Review the routes and authorizers on every release; unreviewed open routes are the usual cause of an incident.

Use AWS CloudTrail to see who changed an API, AWS Config for configuration history and rules, and AWS Artifact for compliance reports. API Gateway is in scope for many assurance programmes, but responsibility is shared: AWS runs the service, and you own the routes, authorisation, data and logs.

• Return less. Smaller responses and compressed bodies mean less traffic and less energy for the same job.
• Cache so repeated requests don’t wake the back end at all.
• Reject bad traffic at the edge with WAF and throttling, not after it has used compute.
• Choose a Region close to your users and, where latency and data rules allow, one with a lower-carbon grid.
• Retire APIs and test environments that nobody calls.
• Prefer events over polling, so clients aren’t hammering a route every few seconds.
• The AWS Customer Carbon Footprint Tool shows estimated emissions for your account. Check what it covers for API Gateway before quoting a number.

Purchase options

What you actually pay for

• Calls received (per million), at a lower rate for HTTP APIs and for very high volumes
• Data transferred out, except for private APIs
• REST API cache, by hour and size
• WebSocket messages and connection minutes
• The services around it: Lambda, CloudWatch Logs, WAF, NAT, data transfer and custom-domain certificates handled outside ACM

An HTTP API that sends two routes to one Lambda function and only lets callers with a valid JWT through. The CLI and Terraform tabs build it, with a throttle and access logs. The Python and C# tabs hold the handler: they read the caller from the token claims and answer with JSON. Replace the placeholder names, the account ID and the identity provider details with your own.

# Assumes the function orders-handler already exists, and that you have a Cognito user pool (or another OIDC provider) for the JWT check
REGION=ap-south-1
ACCOUNT=123456789012
FUNCTION_ARN=arn:aws:lambda:$REGION:$ACCOUNT:function:orders-handler

# An empty HTTP API
API_ID=$(aws apigatewayv2 create-api --name orders-api --protocol-type HTTP \
  --cors-configuration '{"AllowOrigins":["https://app.example.com"],"AllowMethods":["GET","POST"],"AllowHeaders":["authorization","content-type"]}' \
  --query ApiId --output text)

# Connect it to the function (payload format 2.0 is the one the Python and C# samples expect)
INTEGRATION_ID=$(aws apigatewayv2 create-integration --api-id $API_ID \
  --integration-type AWS_PROXY --integration-uri $FUNCTION_ARN \
  --payload-format-version 2.0 --query IntegrationId --output text)

# Check the JWT in the Authorization header before anything reaches the function
AUTH_ID=$(aws apigatewayv2 create-authorizer --api-id $API_ID --name orders-jwt --authorizer-type JWT \
  --identity-source '$request.header.Authorization' \
  --jwt-configuration Audience=your-app-client-id,Issuer=https://cognito-idp.$REGION.amazonaws.com/your-user-pool-id \
  --query AuthorizerId --output text)

# Two routes, both protected
for ROUTE in "GET /orders" "POST /orders"; do
  aws apigatewayv2 create-route --api-id $API_ID --route-key "$ROUTE" \
    --target integrations/$INTEGRATION_ID --authorization-type JWT --authorizer-id $AUTH_ID
done

# Let API Gateway invoke the function, and only this API
aws lambda add-permission --function-name orders-handler --statement-id orders-api \
  --action lambda:InvokeFunction --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:$REGION:$ACCOUNT:$API_ID/*/*"

# Publish to the default stage with a throttle and access logs
aws apigatewayv2 create-stage --api-id $API_ID --stage-name '$default' --auto-deploy \
  --default-route-settings ThrottlingRateLimit=50,ThrottlingBurstLimit=100 \
  --access-log-settings DestinationArn=arn:aws:logs:$REGION:$ACCOUNT:log-group:/aws/apigw/orders-api,Format='$context.requestId $context.identity.sourceIp $context.routeKey $context.status $context.responseLatency'

echo "https://$API_ID.execute-api.$REGION.amazonaws.com/orders"

# Assumes aws_lambda_function.orders exists, plus var.region, var.user_pool_id and var.app_client_id for the JWT check
resource "aws_cloudwatch_log_group" "api" {
  name              = "/aws/apigw/orders-api"
  retention_in_days = 30
}

resource "aws_apigatewayv2_api" "orders" {
  name          = "orders-api"
  protocol_type = "HTTP"

  cors_configuration {
    allow_origins = ["https://app.example.com"]
    allow_methods = ["GET", "POST"]
    allow_headers = ["authorization", "content-type"]
  }
}

resource "aws_apigatewayv2_integration" "orders" {
  api_id                 = aws_apigatewayv2_api.orders.id
  integration_type       = "AWS_PROXY"
  integration_method     = "POST"
  integration_uri        = aws_lambda_function.orders.invoke_arn
  payload_format_version = "2.0"
}

resource "aws_apigatewayv2_authorizer" "jwt" {
  api_id           = aws_apigatewayv2_api.orders.id
  name             = "orders-jwt"
  authorizer_type  = "JWT"
  identity_sources = ["$request.header.Authorization"]

  jwt_configuration {
    audience = [var.app_client_id]
    issuer   = "https://cognito-idp.${var.region}.amazonaws.com/${var.user_pool_id}"
  }
}

resource "aws_apigatewayv2_route" "orders" {
  for_each           = toset(["GET /orders", "POST /orders"])
  api_id             = aws_apigatewayv2_api.orders.id
  route_key          = each.key
  target             = "integrations/${aws_apigatewayv2_integration.orders.id}"
  authorization_type = "JWT"
  authorizer_id      = aws_apigatewayv2_authorizer.jwt.id
}

resource "aws_apigatewayv2_stage" "default" {
  api_id      = aws_apigatewayv2_api.orders.id
  name        = "$default"
  auto_deploy = true

  default_route_settings {
    throttling_rate_limit  = 50
    throttling_burst_limit = 100
  }

  access_log_settings {
    destination_arn = aws_cloudwatch_log_group.api.arn
    format = jsonencode({
      requestId = "$context.requestId"
      ip        = "$context.identity.sourceIp"
      route     = "$context.routeKey"
      status    = "$context.status"
      latency   = "$context.responseLatency"
    })
  }
}

resource "aws_lambda_permission" "api" {
  statement_id  = "AllowOrdersApi"
  action        = "lambda:InvokeFunction"
  function_name = aws_lambda_function.orders.function_name
  principal     = "apigateway.amazonaws.com"
  source_arn    = "${aws_apigatewayv2_api.orders.execution_arn}/*/*"
}

output "invoke_url" {
  value = aws_apigatewayv2_stage.default.invoke_url
}

# lambda_function.py (payload format 2.0, the default for HTTP APIs)
import base64
import json
import logging

logger = logging.getLogger()
logger.setLevel(logging.INFO)


def reply(status, body, request_id):
    return {
        "statusCode": status,
        "headers": {"Content-Type": "application/json", "X-Request-Id": request_id},
        "body": json.dumps(body),  # a string, not a dict: a proxy integration needs it that way
    }


def handler(event, context):
    ctx = event["requestContext"]
    request_id = ctx["requestId"]

    # The JWT authorizer has already checked the token; its claims arrive with the request
    claims = ctx.get("authorizer", {}).get("jwt", {}).get("claims", {})
    user = claims.get("sub")
    if not user:
        return reply(401, {"error": "no user in the token"}, request_id)

    method = ctx["http"]["method"]

    if method == "GET":
        params = event.get("queryStringParameters") or {}
        try:
            limit = min(int(params.get("limit", "20")), 100)
        except ValueError:
            return reply(400, {"error": "limit must be a number"}, request_id)
        return reply(200, {"user": user, "limit": limit, "orders": []}, request_id)

    if method == "POST":
        raw = event.get("body") or "{}"
        if event.get("isBase64Encoded"):
            raw = base64.b64decode(raw).decode("utf-8")
        try:
            order = json.loads(raw)
        except json.JSONDecodeError:
            return reply(400, {"error": "the body is not valid JSON"}, request_id)
        if not isinstance(order, dict) or not order.get("item"):
            return reply(400, {"error": "item is required"}, request_id)

        logger.info(json.dumps({"requestId": request_id, "user": user, "action": "create_order"}))
        return reply(201, {"id": request_id, "item": order["item"]}, request_id)

    return reply(405, {"error": "method not allowed"}, request_id)

// Function.cs: a .NET Lambda handler for an HTTP API (payload format 2.0)
// NuGet packages: Amazon.Lambda.Core, Amazon.Lambda.APIGatewayEvents, Amazon.Lambda.Serialization.SystemTextJson
using System.Text;
using System.Text.Json;
using Amazon.Lambda.APIGatewayEvents;
using Amazon.Lambda.Core;

[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace OrdersApi;

public class Function
{
    public APIGatewayHttpApiV2ProxyResponse Handler(APIGatewayHttpApiV2ProxyRequest request, ILambdaContext context)
    {
        var requestId = request.RequestContext.RequestId;

        // The JWT authorizer has already checked the token; its claims arrive with the request
        string? user = null;
        request.RequestContext.Authorizer?.Jwt?.Claims?.TryGetValue("sub", out user);
        if (string.IsNullOrEmpty(user))
        {
            return Reply(401, new { error = "no user in the token" }, requestId);
        }

        switch (request.RequestContext.Http.Method)
        {
            case "GET":
                var limit = 20;
                var query = request.QueryStringParameters;
                if (query is not null && query.TryGetValue("limit", out var text) && !int.TryParse(text, out limit))
                {
                    return Reply(400, new { error = "limit must be a number" }, requestId);
                }
                return Reply(200, new { user, limit = Math.Min(limit, 100), orders = Array.Empty<string>() }, requestId);

            case "POST":
                var raw = request.Body ?? "{}";
                if (request.IsBase64Encoded)
                {
                    raw = Encoding.UTF8.GetString(Convert.FromBase64String(raw));
                }
                try
                {
                    using var doc = JsonDocument.Parse(raw);
                    if (!doc.RootElement.TryGetProperty("item", out var item) || item.ValueKind != JsonValueKind.String)
                    {
                        return Reply(400, new { error = "item is required" }, requestId);
                    }
                    context.Logger.LogInformation(JsonSerializer.Serialize(new { requestId, user, action = "create_order" }));
                    return Reply(201, new { id = requestId, item = item.GetString() }, requestId);
                }
                catch (JsonException)
                {
                    return Reply(400, new { error = "the body is not valid JSON" }, requestId);
                }

            default:
                return Reply(405, new { error = "method not allowed" }, requestId);
        }
    }

    private static APIGatewayHttpApiV2ProxyResponse Reply(int status, object body, string requestId) => new()
    {
        StatusCode = status,
        Headers = new Dictionary<string, string> { ["Content-Type"] = "application/json", ["X-Request-Id"] = requestId },
        Body = JsonSerializer.Serialize(body)
    };
}

Short walkthrough videos for this service are being prepared. They will appear here and load only when you press play. Until then, follow CloudBrum on YouTube for new videos.

Not sure a gateway is what you need? A Lambda function URL gives one function its own HTTPS address, an Application Load Balancer fronts containers, and AWS AppSync covers GraphQL.