OnCallReadyStart learning

AWS Lesson 39.12 · AWS VI: Architecting on AWS & the exams · 16 min read

API Gateway: putting an API in front of functions

In plain words

API Gateway is the reception desk of an office building. Visitors arrive at one entrance, the desk checks where they want to go, sends them to the right room, and turns people away when the lobby is too full. If the room never answers, the desk eventually tells the visitor "sorry, nobody came" - that is a 504. If the room answers with nonsense, the desk says "something went wrong in there" - a 502. And if the desk cannot even reach the room because nobody gave it the key, that is a 500.

API Gateway: putting an API in front of functions

A Lambda function has no URL of its own (unless you give it a function URL). Amazon API Gateway is the managed front door: it terminates HTTPS, maps paths and methods to integrations (a Lambda function, an HTTP backend, an AWS service), throttles, authenticates and logs - and it answers with its own error codes when the integration misbehaves. Knowing which component produced a 403, 500, 502, 504 or 429 is most of operating an API.

Need to know: two flavours. HTTP APIs (aws apigatewayv2) are the newer, simpler and cheaper ones: routes like GET /items/{id}, Lambda and HTTP integrations, JWT authorizers, CORS, auto-deploying stages. REST APIs (aws apigateway) are older and richer: resources and methods, usage plans and API keys, request validation and mapping templates, response caching, AWS WAF, private APIs, edge-optimized endpoints. Either way API Gateway invokes Lambda as a service, so the function needs a resource-based permission for apigateway.amazonaws.com. The integration timeout is 29 seconds for REST (raisable for Regional APIs) and 30 seconds for HTTP APIs; the account default throttle is 10,000 requests per second with a 5,000 burst.

An HTTP API in one command

try-quote returns a price; its handler can also crash, return garbage or be slow when asked to. Quick create makes an HTTP API with a $default route and stage pointing at it:

$ cd ~/oncall-lab/labs/aws/try6
$ H=$(aws apigatewayv2 create-api --name try-quote-http --protocol-type HTTP --target arn:aws:lambda:eu-central-1:111122223333:function:try-quote --query ApiId --output text)
$ aws apigatewayv2 get-api --api-id $H --query '[Name,ProtocolType,ApiEndpoint]' --output text
try-quote-http	HTTP	https://qclqnntpot.execute-api.eu-central-1.amazonaws.com
$ curl -s -w ' %{http_code}\n' https://$H.execute-api.eu-central-1.amazonaws.com/items/7
{"message":"Internal Server Error"} 500

A 500 before the function even ran: API Gateway may not invoke it. Grant it - scoped to this API with --source-arn, so no other API (and no other account) can use the permission:

$ aws lambda add-permission --function-name try-quote --statement-id http-api --action lambda:InvokeFunction --principal apigateway.amazonaws.com --source-arn "arn:aws:execute-api:eu-central-1:111122223333:$H/*" --query Statement --output text
{"Sid":"http-api","Effect":"Allow","Principal":{"Service":"apigateway.amazonaws.com"},"Action":"lambda:InvokeFunction","Resource":"arn:aws:lambda:eu-central-1:111122223333:function:try-quote","Condition":{"ArnLike":{"AWS:SourceArn":"arn:aws:execute-api:eu-central-1:111122223333:qclqnntpot/*"}}}
$ curl -s -w ' %{http_code}\n' https://$H.execute-api.eu-central-1.amazonaws.com/items/7
{"item":null,"price":42} 200
$ curl -s -w ' %{http_code}\n' "https://$H.execute-api.eu-central-1.amazonaws.com/items/7?crash=1"
{"message":"Internal Server Error"} 500

With an HTTP API (payload format 2.0) the function may return a plain object and API Gateway turns it into a 200 JSON response; a thrown error is a 500 Internal Server Error.

A REST API, piece by piece

A REST API is built from resources (path segments, {id} for a parameter), methods on them, an integration per method, and a deployment to a stage. The Lambda proxy integration (AWS_PROXY) passes the whole request to the function and expects {statusCode, headers, body} back, body a string:

$ R=$(aws apigateway create-rest-api --name try-quote-rest --endpoint-configuration types=REGIONAL --query id --output text)
$ ROOT=$(aws apigateway get-resources --rest-api-id $R --query 'items[0].id' --output text)
$ I=$(aws apigateway create-resource --rest-api-id $R --parent-id $ROOT --path-part items --query id --output text)
$ ID=$(aws apigateway create-resource --rest-api-id $R --parent-id $I --path-part '{id}' --query id --output text)
$ aws apigateway put-method --rest-api-id $R --resource-id $ID --http-method GET --authorization-type NONE --query httpMethod --output text
GET
$ aws apigateway put-integration --rest-api-id $R --resource-id $ID --http-method GET --type AWS_PROXY --integration-http-method POST --uri arn:aws:apigateway:eu-central-1:lambda:path/2015-03-31/functions/arn:aws:lambda:eu-central-1:111122223333:function:try-quote/invocations --query '[type,timeoutInMillis]' --output text
AWS_PROXY	29000
$ aws apigateway create-deployment --rest-api-id $R --stage-name prod --query id --output text
178186
$ aws lambda add-permission --function-name try-quote --statement-id rest-api --action lambda:InvokeFunction --principal apigateway.amazonaws.com --source-arn "arn:aws:execute-api:eu-central-1:111122223333:$R/*/GET/items/*" >/dev/null
$ U=https://$R.execute-api.eu-central-1.amazonaws.com/prod
$ curl -si $U/items/7 | grep -i '^HTTP\|^x-amzn-requestid\|^{'
HTTP/2 200
x-amzn-requestid: 31acf535-3666-45d0-9a6b-a79954030213
{"item":"7","price":42}

Note the integration method is always POST for Lambda (that is how Lambda's Invoke API is called), whatever the client's method. And a change to a method or integration does nothing until you create-deployment again - a stage serves the snapshot it was deployed with.

Reading API Gateway's errors

$ curl -s -w ' %{http_code}\n' $U/item/7
{"message":"Missing Authentication Token"} 403
$ curl -s -w ' %{http_code}\n' "$U/items/7?crash=1"
{"message": "Internal server error"} 502
$ curl -s -w ' %{http_code}\n' "$U/items/7?bad=1"
{"message": "Internal server error"} 502
$ curl -s -w ' %{http_code} after %{time_total}s\n' "$U/items/7?slow=31000"
{"message": "Endpoint request timed out"} 504 after 29.020443s
Status and bodyWhoMeans
403 Missing Authentication TokenAPI Gatewayno such resource / method on this stage (a typo in the path), or an IAM-auth method called unsigned
403 ForbiddenAPI GatewayAPI key required and missing, a resource policy, or WAF
500 Internal server errorAPI Gatewayit could not invoke the integration - usually the missing Lambda permission
502 Internal server errorthe integrationthe function threw, or returned something that is not {statusCode, body}
504 Endpoint request timed outAPI Gatewaythe integration ran past its timeout (29 s)
429 Too Many Requests / Limit ExceededAPI Gatewaystage / route / usage plan throttling, or a usage plan's quota

The function's own logs separate the 502 cases: an Invoke Error line means it threw; a clean REPORT with no error means it returned the wrong shape. A 504 also leaves the function running to its timeout and billing for it - set the function's timeout below the integration's, and give its downstream calls their own timeouts, so slow dependencies fail fast with a proper 503.

Throttling and usage plans

Throttling is a token bucket: the rate refills it every second, the burst is its size. Set it on the stage (all methods, or per method) - here absurdly low to see it:

$ aws apigateway update-stage --rest-api-id $R --stage-name prod --patch-operations op=replace,path=/*/*/throttling/rateLimit,value=1 op=replace,path=/*/*/throttling/burstLimit,value=1 --query 'methodSettings' --output json
{
    "*/*": {
        "metricsEnabled": false,
        "dataTraceEnabled": false,
        "throttlingBurstLimit": 1,
        "throttlingRateLimit": 1,
        "cachingEnabled": false,
        "cacheTtlInSeconds": 300,
        "cacheDataEncrypted": false,
        "requireAuthorizationForCacheControl": true,
        "unauthorizedCacheControlHeaderStrategy": "SUCCEED_WITH_RESPONSE_HEADER"
    }
}
$ for i in 1 2 3 4; do curl -s -o /dev/null -w '%{http_code} ' $U/items/7; done; echo
200 429 429 429
$ aws cloudwatch get-metric-statistics --namespace AWS/ApiGateway --metric-name 4XXError --dimensions Name=ApiName,Value=try-quote-rest Name=Stage,Value=prod --start-time $(date -u -d '-1 hour' +%FT%TZ) --end-time $(date -u -d '+1 hour' +%FT%TZ) --period 7200 --statistics Sum --query 'Datapoints[0].Sum'
4

Throttles are 4XX errors in CloudWatch, the integration's failures 5XX; Latency vs IntegrationLatency tells you whether time is spent in API Gateway or behind it. For many clients with different limits, REST APIs have usage plans: each client gets an API key (sent as x-api-key), the plan sets its rate, burst and a daily or monthly quota (over it: 429 Limit Exceeded). API keys identify clients for metering - they are not authentication; use IAM, a Cognito user pool or a Lambda authorizer for that.

Other front doors for a function: a function URL (https://<id>.lambda-url.<region>.on.aws/, no throttling or keys, IAM or no auth) for webhooks and internal tools, and an ALB with a Lambda target group when the function sits next to containers behind the same load balancer.

On the exam (SAA-C03 2.1, 3.3, 4.4 "throttling strategies"; SOA-C03 1.3, 4.1): REST vs HTTP API (usage plans, API keys, caching, WAF, private endpoints = REST; cheaper and simpler = HTTP), stage throttling and usage plans, 29-second integration timeout, 502 vs 504, the Lambda permission for apigateway.amazonaws.com, API Gateway caching to cut backend load.

In an interview: "Your API returns 502 under load but 200 when you test it by hand. Where do you look?" - "A 502 comes from the integration: the Lambda function threw or returned a malformed response. Under load that is usually an error path - a downstream timeout, throttling of the function or the database - that returns something which is not a proxy response. I'd read the function's logs for Invoke Error lines around the 5XXError spike and check its Throttles and duration."

You can now: create HTTP and REST APIs in front of a function, grant API Gateway a scoped permission, deploy to a stage, tell API Gateway's 403 / 500 / 502 / 504 / 429 apart and find the cause, throttle a stage, explain usage plans and API keys, and choose between an HTTP API, a REST API, a function URL and an ALB.

Why it helps

Most serverless applications are reached through API Gateway, and most of their user-visible errors are API Gateway's own status codes. Knowing which component produced a 403, 500, 502, 504 or 429, how REST and HTTP APIs differ, how the Lambda permission works and how throttling and usage plans protect the backend makes the difference between guessing and fixing during an incident.

Commands in this lesson

cd aws curl

FAQ

Why does my new API return 403 Missing Authentication Token?

For a REST API, any path or method that does not exist on the deployed stage answers 403 Missing Authentication Token - often a typo, a missing stage name in the URL, or a method added after the last deployment. Check the URL and run create-deployment again after changing methods.

What is the difference between a 502 and a 504 from API Gateway?

A 502 means the integration answered badly: the Lambda function threw an error or returned something that is not a proxy response with statusCode and a string body. A 504 means the integration did not answer within its timeout, 29 seconds by default for REST APIs. The function's logs show which one happened.

Why does API Gateway need a Lambda permission?

API Gateway invokes the function as the service principal apigateway.amazonaws.com, so the function's resource-based policy must allow it. Scope it with a source ARN naming your API, stage and path; otherwise any API in any account that points at your function could use the permission. Without it, the API answers 500.

Are API keys a security mechanism?

No. API keys identify clients for usage plans - rate limits, burst limits and quotas - and can be shared or leaked like any string. For authentication use IAM authorization, a Cognito user pool or JWT authorizer, or a Lambda authorizer, and treat keys only as metering.

When is an HTTP API not enough?

When you need REST-API-only features: usage plans and API keys, per-method throttling, request validation and mapping templates, response caching, AWS WAF directly on the API, private APIs inside a VPC, or edge-optimized endpoints. Otherwise HTTP APIs are cheaper and simpler.

In an interview Mid

Your API returns 502 under load but works when you test it by hand. Where do you look?

A 502 comes from the integration, so I read the Lambda function's logs around the 5XXError spike for Invoke Error lines and REPORT lines with a timeout status. Under load the usual cause is an error path - a slow dependency, throttling - that returns something that is not a proxy response with statusCode and a string body. I would fix the error path, add timeouts to downstream calls below the integration timeout, and watch Throttles and Duration.

Also asked: What is the difference between a REST API and an HTTP API? · How do you throttle an API per client? · What does API Gateway need to invoke a Lambda function?

Practise this lesson in the terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.