API Gateway — Amazon API Gateway

AWS docs: https://docs.aws.amazon.com/apigateway/latest/api/Welcome.html

API Gateway (REST v1 and HTTP v2) uses a REST API with path-based routing. REST API v1 is mounted at /restapis, HTTP API v2 at /v2/apis.

---

Known limitations

• No VTL template mapping. Integration request/response templates are not evaluated as VTL — values are passed through as-is.
• Partial authorizer enforcement. COGNITO_USER_POOLS (REST v1) and JWT (HTTP v2) authorizers are validated (RS256 signature + expiry + issuer/audience). Lambda (TOKEN, REQUEST) and IAM authorizers are stored but not enforced at request time.
• No request validation. Request validators are stored but not enforced at request time.
• No WebSocket execution. WEBSOCKET protocol type is accepted on creation but execution is not implemented.
• Usage counters are not persisted. Quota and throttle state lives in memory so the request path never hits the store; restarting Overcast resets it. Real API Gateway carries a quota across the whole period.
• Usage plans only apply to REST v1. As on AWS, HTTP APIs (v2) have no API-key or usage-plan concept, so nothing is measured or enforced there.

Usage plan throttling and quotas

A method with apiKeyRequired: true resolves the caller’s x-api-key to an API key and to the usage plan covering {restApiId, stage} — a request with no such plan is already refused with 403 Forbidden. Once the plan is found, its limits are measured on every request:

• Throttle — throttle.rateLimit is the tokens-per-second refill and throttle.burstLimit the bucket capacity, the token-bucket model AWS documents. The bucket is per (usage plan, API key), not per plan.
• Quota — quota.limit requests per quota.period (DAY, WEEK, MONTH) in calendar-aligned UTC windows; quota.offset is subtracted from the limit in the first period only. Windows roll over on the injected clock, so tests can fast-forward them.

Read the counters back with GetUsage, which returns AWS’s daily [used, remaining] log per API key (a date range wider than 400 days is refused with BadRequestException — AWS documents no such cap, but the response carries one entry per day per key). Reaching a limit also logs a warning and publishes an apigateway:Throttled event — visible on the web UI’s Events page and on the Usage Plans page — coalesced to at most one per key per second.

Rejection is opt-in and off by default. Overcast is not a rate-limiting or load-testing tool, and switching enforcement on can turn a local stack that works today into one that gets 429s it never used to. So by default an over-limit request is counted, reported, and then served normally. Set OVERCAST_ENFORCE_APIGATEWAY_THROTTLE=true to have over-limit requests rejected the way AWS rejects them:

Condition	Status	x-amzn-ErrorType	Body
Rate/burst exceeded (THROTTLED)	429	TooManyRequestsException	{"message":"Too Many Requests"}
Quota exhausted (QUOTA_EXCEEDED)	429	LimitExceededException	{"message":"Limit Exceeded"}

A rejected request consumes neither quota nor a token, matching AWS — a 429 does not count against the usage plan quota. A plan configuring neither a throttle nor a quota never rejects anything, whatever the flag says.

Invoke URLs

REST v1 and HTTP v2 APIs are reachable two ways, with identical behaviour:

• Path-style — http://localhost:4566/restapis/{apiId}/{stage}/_user_request_/...
• Host-routed — http://{apiId}.execute-api.{region}.{base}/{stage}/..., the shape real AWS uses. {base} is whatever hostname you reached Overcast on; set OVERCAST_HOSTNAME=localhost.overcast.sh so it resolves on every OS.

HTTP v2 APIs report the host-routed form in apiEndpoint, minted on the hostname you called Overcast on rather than amazonaws.com, so CloudFormation’s Fn::GetAtt ApiEndpoint returns a URL you can dial. REST v1 has no such field, matching AWS — the console composes it client-side, and it composes the host-routed form too, falling back to path-style only when the endpoint it is connected to cannot carry a subdomain (a bare localhost, or an IP). That is the URL its copy button yields.

Stack outputs that compose an invoke URL in the template (as CDK does) are also re-hosted onto a reachable origin when returned by DescribeStacks. See networking.md.

Summary

Category	✅ Supported	❌ Unsupported
REST API v1 management	24
REST API v1 stages	7
REST API v1 other	34	2
HTTP API v2 management	15
HTTP API v2 stages	6
HTTP API v2 other	17
REST API v1 execution	1

---

Endpoints

REST API v1 management

Operation	Status	Notes	AWS Docs
CreateRestApi	✅ Supported	Creates API with root / resource; default EDGE endpoint type	docs
GetRestApi	✅ Supported		docs
GetRestApis	✅ Supported	Pagination not yet implemented	docs
DeleteRestApi	✅ Supported	Cascade deletes resources, stages, and deployments	docs
UpdateRestApi	✅ Supported	Patch /name, /description, /policy, /disableExecuteApiEndpoint	docs
CreateResource	✅ Supported	Computes full path from parent chain	docs
GetResource	✅ Supported		docs
GetResources	✅ Supported	Pagination not yet implemented	docs
DeleteResource	✅ Supported		docs
UpdateResource	✅ Supported	Patch /pathPart	docs
PutMethod	✅ Supported		docs
GetMethod	✅ Supported		docs
DeleteMethod	✅ Supported		docs
UpdateMethod	✅ Supported	Patch /authorizationType, /authorizerId, /apiKeyRequired	docs
PutIntegration	✅ Supported	AWS_PROXY/MOCK/HTTP_PROXY/HTTP/AWS types; uri, httpMethod	docs
GetIntegration	✅ Supported		docs
DeleteIntegration	✅ Supported		docs
UpdateIntegration	✅ Supported	Patch integrationType, integrationUri, payloadFormatVersion	docs
PutMethodResponse	✅ Supported		docs
GetMethodResponse	✅ Supported		docs
DeleteMethodResponse	✅ Supported		docs
PutIntegrationResponse	✅ Supported	responseTemplates, selectionPattern	docs
GetIntegrationResponse	✅ Supported		docs
DeleteIntegrationResponse	✅ Supported		docs

REST API v1 stages

Operation	Status	Notes	AWS Docs
CreateDeployment	✅ Supported		docs
GetDeployments	✅ Supported		docs
CreateStage	✅ Supported	Links to a deployment	docs
GetStage	✅ Supported		docs
GetStages	✅ Supported		docs
UpdateStage	✅ Supported	Patch /description, /deploymentId, and per-key /variables/{name} (replace/add/remove); MethodSettings, TracingEnabled, AccessLogSetting, CacheClusterEnabled/Size, ClientCertificateId, DocumentationVersion not implemented	docs
DeleteStage	✅ Supported		docs

REST API v1 other

Operation	Status	Notes	AWS Docs
CreateModel	✅ Supported	id, name, contentType, schema, description	docs
GetModel	✅ Supported		docs
GetModels	✅ Supported		docs
DeleteModel	✅ Supported		docs
CreateAuthorizer	✅ Supported	JWT and REQUEST types; config stored	docs
GetAuthorizer	✅ Supported		docs
GetAuthorizers	✅ Supported		docs
DeleteAuthorizer	✅ Supported		docs
CreateRequestValidator	✅ Supported	validateRequestBody, validateRequestParams	docs
GetRequestValidators	✅ Supported		docs
DeleteRequestValidator	✅ Supported		docs
CreateApiKey	✅ Supported	auto-generated key value	docs
GetApiKey	✅ Supported		docs
GetApiKeys	✅ Supported		docs
DeleteApiKey	✅ Supported		docs
CreateUsagePlan	✅ Supported	throttle (token bucket) and quota measured per API key; rejection needs OVERCAST_ENFORCE_APIGATEWAY_THROTTLE	docs
GetUsagePlan	✅ Supported		docs
GetUsagePlans	✅ Supported		docs
DeleteUsagePlan	✅ Supported		docs
CreateUsagePlanKey	✅ Supported		docs
GetUsagePlanKeys	✅ Supported		docs
DeleteUsagePlanKey	✅ Supported		docs
GetUsage	✅ Supported	daily [used, remaining] log per API key; counts are in-memory and reset on restart	docs
CreateDomainName	✅ Supported	Inert metadata; no routing effect	docs
GetDomainNames	✅ Supported		docs
DeleteDomainName	✅ Supported		docs
CreateBasePathMapping	✅ Supported	Stored under the domain name	docs
GetBasePathMappings	✅ Supported		docs
CreateVpcLink	✅ Supported	Status immediately AVAILABLE; no VPC connectivity enforced	docs
GetVpcLinks	✅ Supported		docs
DeleteVpcLink	✅ Supported		docs
TagResource	✅ Supported	PUT /tags/{arn} — merges tags; ARN may contain slashes	docs
UntagResource	✅ Supported	DELETE /tags/{arn}?tagKeys=k1,k2	docs
GetTags	✅ Supported		docs
GetAccount	❌ Unsupported		docs
UpdateAccount	❌ Unsupported		docs

HTTP API v2 management

Operation	Status	Notes	AWS Docs
CreateV2Api	✅ Supported	HTTP and WEBSOCKET protocol types; default route selection	docs
GetV2Api	✅ Supported		docs
GetV2Apis	✅ Supported	Pagination not yet implemented	docs
UpdateV2Api	✅ Supported		docs
DeleteV2Api	✅ Supported	Cascade deletes routes, integrations, stages, deployments	docs
CreateV2Route	✅ Supported		docs
GetV2Route	✅ Supported		docs
GetV2Routes	✅ Supported		docs
DeleteV2Route	✅ Supported		docs
UpdateV2Route	✅ Supported	Patch routeKey, target, authorizationType	docs
CreateIntegration	✅ Supported	AWS_PROXY / HTTP_PROXY types; payloadFormatVersion 1.0/2.0	docs
GetV2Integration	✅ Supported		docs
GetV2Integrations	✅ Supported		docs
DeleteIntegration	✅ Supported		docs
UpdateIntegration	✅ Supported	Patch integrationType, integrationUri, payloadFormatVersion	docs

HTTP API v2 stages

Operation	Status	Notes	AWS Docs
CreateV2Deployment	✅ Supported		docs
GetV2Deployments	✅ Supported		docs
CreateV2Stage	✅ Supported		docs
GetV2Stage	✅ Supported		docs
GetV2Stages	✅ Supported		docs
DeleteV2Stage	✅ Supported		docs

HTTP API v2 other

Operation	Status	Notes	AWS Docs
UpdateV2Stage	✅ Supported	Patch description, autoDeploy, deploymentId, stageVariables	docs
CreateV2Authorizer	✅ Supported	JWT and REQUEST types; config stored	docs
GetV2Authorizer	✅ Supported		docs
GetV2Authorizers	✅ Supported		docs
DeleteV2Authorizer	✅ Supported		docs
CreateV2DomainName	✅ Supported	Inert metadata; no routing effect	docs
GetV2DomainNames	✅ Supported		docs
DeleteV2DomainName	✅ Supported		docs
CreateV2VpcLink	✅ Supported	Status immediately AVAILABLE; no VPC connectivity enforced	docs
GetV2VpcLinks	✅ Supported		docs
DeleteV2VpcLink	✅ Supported		docs
CreateV2ApiMapping	✅ Supported	Stored under the domain name	docs
GetV2ApiMappings	✅ Supported		docs
TagV2Resource	✅ Supported	POST /v2/tags/{arn} — merges tags; ARN may contain slashes	docs
UntagV2Resource	✅ Supported	DELETE /v2/tags/{arn}?tagKeys=k1,k2	docs
GetV2Tags	✅ Supported		docs
ExecuteV2API	✅ Supported	AWS_PROXY and HTTP_PROXY integration types; records the same Count/4xx/5xx/Latency/IntegrationLatency metrics (HTTP APIs use AWS’s lowercase 4xx/5xx metric names, not REST’s 4XXError/5XXError) under all three AWS-documented HTTP dimension combinations — ApiId, ApiId+Stage, and ApiId+Stage+HttpMethod+RouteKey	docs

REST API v1 execution

Operation	Status	Notes	AWS Docs
ExecuteRestAPI	✅ Supported	Lambda proxy/non-proxy, HTTP_PROXY, HTTP, and MOCK integrations; stage variable substitution; base64 Lambda responses decoded before write; records AWS/ApiGateway CloudWatch metrics Count, 4XXError, 5XXError, Latency, and IntegrationLatency once per dispatched request under all three AWS-documented REST dimension combinations — ApiName, ApiName+Stage, and ApiName+Stage+Method+Resource (service-metrics-platform.md phase 2, #1307) — an unresolvable restApiId records nothing, since there is no ApiName to dimension a series with	docs