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 body | Who | Means |
|---|---|---|
403 Missing Authentication Token | API Gateway | no such resource / method on this stage (a typo in the path), or an IAM-auth method called unsigned |
403 Forbidden | API Gateway | API key required and missing, a resource policy, or WAF |
500 Internal server error | API Gateway | it could not invoke the integration - usually the missing Lambda permission |
502 Internal server error | the integration | the function threw, or returned something that is not {statusCode, body} |
504 Endpoint request timed out | API Gateway | the integration ran past its timeout (29 s) |
429 Too Many Requests / Limit Exceeded | API Gateway | stage / 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.