Skip to content

opensite-ai/opensite-skills / aws-serverless

aws-serverless

Verified

Routes serverless requests to a compute form factor and the skill that owns it. Applies first to Lambda, API Gateway, EventBridge, Step Functions and event-driven work while the compute, orchestration or integration choice is open — API backends, webhooks, jobs, cron, queue/stream consumers, durable workflows, event routing, Step Functions vs Durable Functions, and Pipes vs native event source mappings for queues and streams. Decides Event Functions on-demand vs Managed Instances, Web Functions, MicroVMs, EventBridge rules/Scheduler/Pipes/bus, HTTP vs REST API. Owns shared Lambda references (cold starts, SnapStart, concurrency, event sources, function URLs, throttling, troubleshooting). Defers to the specialized skill once a request commits to one form factor or service, or describes its defining feature, even unnamed (durable checkpointing and automatic step retries, Firecracker sandbox, managed instances, Node.js server). Not for EC2, ECS/EKS/Fargate or Amplify hosting.

references/api-gateway.md

View on GitHub
# API Gateway Reference

Exact quotas and the handful of gotchas worth pinning down. Assumes you know the basics: choose **REST API** when you need WAF / API keys / usage plans / request validation / built-in caching / edge-optimized / canary / VTL / resource policies, otherwise **HTTP API** (lower latency, native JWT, built-in CORS, auto-deploy); under Lambda **proxy** integration the **Lambda must return CORS headers** (the console "Enable CORS" button doesn't apply); the **#1 cause of 502** is a malformed proxy response (`body` must be a `JSON.stringify`'d string in the `{statusCode, headers, body}` shape); REST API has **no native generic JWT** (use Cognito or a Lambda authorizer), HTTP API has a **native JWT authorizer** for any OIDC IdP.

## Contents

- [Choosing the HTTP front door](#choosing-the-http-front-door)
- [REST vs HTTP API comparison](#rest-vs-http-api-comparison)
- [Integration timeouts and payloads](#integration-timeouts-and-payloads)
- [Throttling and quotas](#throttling-and-quotas)
- [Lambda authorizers](#lambda-authorizers)
- [WebSocket APIs](#websocket-apis)
- [CORS gotchas](#cors-gotchas)

---

## Choosing the HTTP front door

Decided in `SKILL.md` Step 5; this is the full table.

| Need | Use | Continue with |
|---|---|---|
| Node.js HTTP server, streaming responses, active-CPU billing, CloudFront in front | **Lambda Web Functions** | **aws-lambda-web-functions** skill (not API Gateway) |
| Regional HTTP proxy for Event Functions: lowest latency and cost, JWT/IAM/Lambda authorizers, no per-client throttling, 30 s timeout | **API Gateway HTTP API** | [REST vs HTTP API comparison](#rest-vs-http-api-comparison); **connecting-lambda-to-api-gateway** skill |
| Per-client usage plans and API keys, request validation/transformation, caching, canary deployments, private or edge-optimized endpoints, WAF, response streaming via API Gateway | **API Gateway REST API** | [REST vs HTTP API comparison](#rest-vs-http-api-comparison); **creating-api-gateway-stage**, **deploying-custom-domain-rest-api** skills |
| Persistent bidirectional connections (chat, live dashboards, IoT command and control) with Event Functions | **API Gateway WebSocket API** | [WebSocket APIs](#websocket-apis) |
| Simple HTTPS endpoint for a single Event Function without API management (IAM or public auth, response streaming) | **Lambda Function URL** | [lambda.md](lambda.md) |

Use HTTP API by default — it is the cheaper option (up to ~70% lower per-request price than REST API) with lower latency — and move to REST API only when it lacks a feature you need. State this cost/feature tradeoff explicitly when recommending an API front door.

---

## REST vs HTTP API comparison

Default to **HTTP API** (lower latency, lower cost, simpler); reach for **REST API** only when you need one of its exclusive features:

```
Need any of these? → REST API
  ├── API keys / usage plans / per-client throttling
  ├── Request validation (built-in)
  ├── Request/response body transformation (VTL)
  ├── Caching (built-in)
  ├── Private API endpoints
  ├── Edge-optimized endpoints
  ├── Canary deployments
  ├── Execution logs / X-Ray tracing
  ├── Resource policies
  ├── Mock integrations
  └── Response streaming

None of the above? → HTTP API (lower latency, simpler)
```

---

## Integration timeouts and payloads

| | REST API | HTTP API |
|---|---|---|
| Integration timeout | 50ms–29s (default 29s; **raisable only for Regional/private**) | **30s hard max** (lowerable, not raisable) |
| Payload size | 10 MB | 10 MB |
| Endpoint types | Edge, Regional, Private | Regional only |
| Response streaming | Yes (proxy, STREAM mode) | No |

> **REST API streaming caveats:** no built-in caching, no VTL transforms, no WAF inspection of streamed content; 2 MBps cap after the first 10 MB (Function URLs cap after 6 MB).

---

## Throttling and quotas

Throttling applies most-specific → least-specific: per-client/method (usage plan + API key, REST only) → per-method → account-level → AWS Regional (hard). Token bucket: empty bucket → `429 Too Many Requests`; burst allows temporary spikes.

### Account-level

Confirm the current account-level steady-state RPS and burst limits for the Region rather than assuming a default — they vary by Region and are adjustable:

```bash
aws service-quotas get-service-quota --service-code apigateway --quota-code L-8A5B8E43
```

### REST API

| Resource | Default | Adjustable? |
|---|---|---|
| Resources per API | 300 | Yes |
| Stages per API | 10 | Yes |
| API keys per account | 10,000 | No |
| Usage plans per account | 300 | Yes |
| Custom domains per Region | 120 | Yes |
| Header value size | 10,240 bytes | No |
| Cache TTL | 0–3600s | No |
| Mapping template size | 300 KB | No |

### HTTP API

| Resource | Default | Adjustable? |
|---|---|---|
| Routes per API | 300 | Yes |
| Stages per API | 10 | Yes |
| Integrations per API | 300 | No |
| Custom domains per Region | 120 | Yes |
| VPC links per Region | 10 | Yes |

Client-side 429 handling: exponential backoff with jitter, respect `Retry-After`, rate-limit to stay under known limits.

---

## Lambda authorizers

| Feature | TOKEN | REQUEST |
|---|---|---|
| Identity source | Single header (bearer token) | Headers, query strings, stage vars, `$context` |
| Cache key | Token header value | All specified identity sources combined |
| Available on | REST API only | REST API + HTTP API |
| Recommendation | Legacy | **Preferred for new APIs** |

Caching: default TTL **300s** (range 0–3600). **A cached policy applies to ALL methods/resources.** If any specified identity source is missing/null/empty → **401 without invoking Lambda**.

The authorizer must return an IAM policy: `{ principalId, policyDocument: { Version, Statement: [{ Action: "execute-api:Invoke", Effect: "Allow"|"Deny", Resource: methodArn }] }, context: {...} }`. HTTP API JWT authorizers need no Lambda — configure `issuer` + `audience` directly on the API.

---

## WebSocket APIs

Routes: `$connect` (auth, store connectionId), `$disconnect` (best-effort cleanup), `$default` (catch-all / non-JSON), plus custom routes selected by `$request.body.action`. Server pushes via the `@connections` API (`PostToConnectionCommand` / `post_to_connection`).

| Limit | Value |
|---|---|
| Idle connection timeout | 10 minutes |
| Max connection duration | 2 hours |
| Message payload | 128 KB (hard limit) |

Close codes: **1001** idle/max-duration, 1003 unsupported binary, 1006 abnormal (no close frame), **1008** throttled, **1009** message too large, 1011 internal error, 1012 service restart.

Store `connectionId` in DynamoDB with a **TTL attribute set to now + 7200s** (the 2-hour max duration) so stale connections are auto-cleaned even when `$disconnect` is missed — enable DynamoDB TTL on that attribute.

---

## CORS gotchas

The common, non-obvious failures (basic header setup is well understood):

| Mistake | Fix |
|---|---|
| Binary media types `*/*` break OPTIONS (502) | Set `contentHandling: CONVERT_TO_TEXT` on the OPTIONS integration |
| `Allow-Origin: *` with `credentials: include` | Specify the exact origin, not a wildcard |
| Not redeploying after CORS changes | Redeploy the stage |
| Gateway 4XX/5XX responses lack CORS headers | Add CORS headers to gateway responses too |

For the full step-by-step procedure of wiring CORS, throttling, and access logging when connecting a Lambda, use the **connecting-lambda-to-api-gateway** skill (see SKILL.md routing). For 502/504 deep debugging, see [troubleshooting.md](troubleshooting.md).
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall