feat(aws-serverless): Add Amazon API gateway skill

[giedri]

Adding Amazon API Gateway skill (api-gateway) to aws-serverless plugin

Related

N/A

Changes

New skill — api-gateway (16 reference files):

• requirements-gathering.md — structured requirements workflow, question-driven API design process
• architecture-patterns.md — topology patterns, multi-tenant SaaS, hybrid workloads, private APIs, multi-region, streaming
• authentication.md — auth decision tree, Lambda authorizers, JWT authorizers, Cognito, IAM auth
• security.md — TLS policies, mTLS, resource policies, WAF, HttpOnly cookies, CRL checks
• custom-domains-routing.md — custom domain setup by endpoint type, base path mappings, routing rules, header-based versioning
• service-integrations.md — direct AWS service integrations without Lambda, VTL mapping templates, REST and WebSocket integration approaches
• sam-cloudformation.md — SAM/CloudFormation IaC patterns, OpenAPI extensions, VTL reference, binary data
• sam-service-integrations.md — SAM templates for EventBridge, SQS, DynamoDB CRUD, Kinesis, Step Functions integrations
• websocket.md — route selection, @connections management, session management, client resilience, SAM templates, limits
• performance-scaling.md — throttling, caching, edge caching, scaling considerations
• observability.md — logging, access log formats, enhanced observability variables, CloudWatch alarms, log retention
• deployment.md — deployment strategies, canary deployments, blue/green, routing rules
• governance.md — preventative controls (SCPs, IAM), proactive controls (CloudFormation Hooks), detective controls (Config, EventBridge)
• pitfalls.md — additional gotchas beyond SKILL.md: header handling, URL encoding, caching charges, canary deployments, usage plans
• troubleshooting.md — error diagnosis, status code resolution steps, general debugging approach
• service-limits.md — default quotas for REST, HTTP, and WebSocket APIs, adjustability notes

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[MichaelWalker-git]

LGTM

[scottschreckengaust]

Code review

Found 2 issues:

1. WebSocket SAM template missing AWS::Lambda::Permission for $disconnect and $default routes. The template defines three routes with three Lambda integrations (ConnectFunction, DisconnectFunction, MessageFunction) but only includes ConnectPermission. Without permissions for DisconnectFunction and MessageFunction, API Gateway cannot invoke them, causing silent 500 errors on every message and disconnect. The $disconnect failure is particularly insidious -- it is best-effort delivery so the client never sees the error, and stale connections accumulate in DynamoDB without cleanup.

agent-plugins/plugins/aws-serverless/skills/api-gateway/references/websocket.md

Lines 56 to 99 in 8d4fd21

	DisconnectRoute:
	Type: AWS::ApiGatewayV2::Route
	Properties:
	ApiId: !Ref WebSocketApi
	RouteKey: $disconnect
	Target: !Sub "integrations/${DisconnectIntegration}"
	DisconnectIntegration:
	Type: AWS::ApiGatewayV2::Integration
	Properties:
	ApiId: !Ref WebSocketApi
	IntegrationType: AWS_PROXY
	IntegrationUri: !Sub "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${DisconnectFunction.Arn}/invocations"
	DefaultRoute:
	Type: AWS::ApiGatewayV2::Route
	Properties:
	ApiId: !Ref WebSocketApi
	RouteKey: $default
	Target: !Sub "integrations/${DefaultIntegration}"
	DefaultIntegration:
	Type: AWS::ApiGatewayV2::Integration
	Properties:
	ApiId: !Ref WebSocketApi
	IntegrationType: AWS_PROXY
	IntegrationUri: !Sub "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${MessageFunction.Arn}/invocations"
	Stage:
	Type: AWS::ApiGatewayV2::Stage
	Properties:
	ApiId: !Ref WebSocketApi
	StageName: prod
	AutoDeploy: true
	ConnectPermission:
	Type: AWS::Lambda::Permission
	Properties:
	Action: lambda:InvokeFunction
	FunctionName: !Ref ConnectFunction
	Principal: apigateway.amazonaws.com
	SourceArn: !Sub "arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${WebSocketApi}/*/$connect"
	```

2. VPC Link v2 incorrectly described as supporting REST APIs. Line 121 states "VPC Link v2 (AWS::ApiGatewayV2::VpcLink): Supported by REST and HTTP APIs" -- this is incorrect. AWS::ApiGatewayV2::VpcLink is for HTTP APIs only. REST APIs must use AWS::ApiGateway::VpcLink (v1, NLB-only). Line 122 labels v1 as "legacy REST API integrations" which is misleading since v1 is the only option for REST APIs. The same error appears in service-integrations.md line 152.

agent-plugins/plugins/aws-serverless/skills/api-gateway/references/architecture-patterns.md

Lines 120 to 123 in 8d4fd21

	- **VPC Link v2** (`AWS::ApiGatewayV2::VpcLink`): Supported by REST and HTTP APIs, targets ALB, NLB, and Cloud Map (for HTTP APIs) services. One VPC link per VPC can serve multiple backends. Prefer v2 for new integrations
	- **VPC Link v1** (`AWS::ApiGateway::VpcLink`): Used by WebSocket API (and legacy REST API integrations), targets NLB only
	- **Not the same as private endpoints**: A _private API endpoint_ restricts who can **call** the API (only from within a VPC via `execute-api` VPC endpoint). A _VPC Link_ controls where the API **forwards requests to** (private backends in a VPC). These are independent: a public API can use VPC Links to reach private backends, and a private API can call public HTTP endpoints without VPC Links

agent-plugins/plugins/aws-serverless/skills/api-gateway/references/service-integrations.md

Lines 151 to 153 in 8d4fd21

	- `HTTP` (non-proxy): Allows VTL mapping templates to transform request and response. REST API only
	- **VPC Link** for private backends: Use `connectionType: VPC_LINK` to reach ALB, NLB, or Cloud Map services inside a VPC without exposing them to the internet. VPC Link v2 supports REST and HTTP APIs (targets ALB and NLB); WebSocket API uses VPC Link v1 (NLB only)
	- **Path and parameter passthrough**: Map URL path parameters, query strings, and headers from the method request to the integration request. Use `{proxy+}` greedy path parameter for catch-all routing

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[giedri]

Issue #1 - fixed
Issue #2 - it is not correct statement. As of November 2025 VPC Link v2 supports both HTTP and REST APIs: https://aws.amazon.com/blogs/compute/build-scalable-rest-apis-using-amazon-api-gateway-private-integration-with-application-load-balancer/