Skip to content

cloudthinker-ai/CloudSkills / skills/connections/aws-api-gateway

aws-api-gateway

Verified

Use when working with AWS API Gateway — analyzing REST or HTTP APIs, debugging latency or 5xx errors, auditing throttling and stage configuration, reviewing usage plans, or checking authorization setup. Covers API inventory, CloudWatch metrics, stage audits, and integration health for both REST (v1) and HTTP (v2) APIs.

AWS API Gateway Skill

Analyze AWS API Gateway REST and HTTP APIs with parallel execution and anti-hallucination guardrails.

Decision Matrix: REST vs HTTP API

NeedUseWhy
Usage plans / API keysREST APIHTTP APIs don't support usage plans
Request validation / WAFREST APINot available in HTTP API
Execution logging / X-RayREST APIHTTP API only supports access logging
Lowest costHTTP API$1/M vs $3.50/M requests
WebSocket supportHTTP API (v2)Only v2 supports WebSocket protocol
Auto-deployHTTP APIREST requires explicit deployment
Simple proxy to LambdaHTTP APISimpler, cheaper, auto-deploy

Full feature comparison

Phase 1 — Discovery

CRITICAL: Discover both REST and HTTP APIs in parallel. NEVER assume API names or IDs.

#!/bin/bash
export AWS_PAGER=""

echo "=== REST APIs (apigateway) ==="
aws apigateway get-rest-apis \
  --output text \
  --query 'items[].[id,name,endpointConfiguration.types[0]]' &

echo "=== HTTP APIs (apigatewayv2) ==="
aws apigatewayv2 get-apis \
  --output text \
  --query 'Items[].[ApiId,Name,ProtocolType]' &
wait

Phase 2 — Analysis

Run ALL independent operations in parallel using & and wait.

Latency & Error Analysis

#!/bin/bash
export AWS_PAGER=""
END=$(date -u +"%Y-%m-%dT%H:%M:%S")
START=$(date -u -d "7 days ago" +"%Y-%m-%dT%H:%M:%S" 2>/dev/null || date -u -v-7d +"%Y-%m-%dT%H:%M:%S")

# REST APIs: use ApiName dimension
APIS=$(aws apigateway get-rest-apis --output text --query 'items[].[name]')
for api in $APIS; do
  {
    latency=$(aws cloudwatch get-metric-statistics \
      --namespace AWS/ApiGateway --metric-name Latency \
      --dimensions Name=ApiName,Value="$api" \
      --start-time "$START" --end-time "$END" \
      --period 604800 --statistics Average Maximum \
      --output text --query 'Datapoints[0].[Average,Maximum]')
    errors=$(aws cloudwatch get-metric-statistics \
      --namespace AWS/ApiGateway --metric-name 5XXError \
      --dimensions Name=ApiName,Value="$api" \
      --start-time "$START" --end-time "$END" \
      --period 604800 --statistics Sum \
      --output text --query 'Datapoints[0].Sum')
    printf "REST\t%s\tLatency:%s\t5xx:%s\n" "$api" "$latency" "${errors:-0}"
  } &
done

# HTTP APIs: use ApiId dimension and lowercase metric names
HTTP_APIS=$(aws apigatewayv2 get-apis --output text --query 'Items[].[ApiId,Name]')
echo "$HTTP_APIS" | while read api_id api_name; do
  {
    latency=$(aws cloudwatch get-metric-statistics \
      --namespace AWS/ApiGateway --metric-name Latency \
      --dimensions Name=ApiId,Value="$api_id" \
      --start-time "$START" --end-time "$END" \
      --period 604800 --statistics Average Maximum \
      --output text --query 'Datapoints[0].[Average,Maximum]')
    errors=$(aws cloudwatch get-metric-statistics \
      --namespace AWS/ApiGateway --metric-name 5xx \
      --dimensions Name=ApiId,Value="$api_id" \
      --start-time "$START" --end-time "$END" \
      --period 604800 --statistics Sum \
      --output text --query 'Datapoints[0].Sum')
    printf "HTTP\t%s(%s)\tLatency:%s\t5xx:%s\n" "$api_name" "$api_id" "$latency" "${errors:-0}"
  } &
done
wait

Stage Configuration Audit

#!/bin/bash
export AWS_PAGER=""
APIS=$(aws apigateway get-rest-apis --output text --query 'items[].id')
for api_id in $APIS; do
  aws apigateway get-stages --rest-api-id "$api_id" \
    --output text \
    --query "item[].[\"$api_id\",stageName,cacheClusterEnabled,tracingEnabled,methodSettings.*.loggingLevel]" &
done
wait

Throttling Review

#!/bin/bash
export AWS_PAGER=""
# Account-level limits
aws apigateway get-account \
  --output text --query '[throttleSettings.burstLimit,throttleSettings.rateLimit]'

# Usage plans (REST only)
aws apigateway get-usage-plans \
  --output text \
  --query 'items[].[id,name,throttle.burstLimit,throttle.rateLimit,quota.limit,quota.period]'

Anti-Hallucination Rules

RuleDetail
REST vs HTTP CLIapigateway (REST/v1) vs apigatewayv2 (HTTP/WebSocket). NEVER mix.
CloudWatch dimensionsREST uses ApiName; HTTP uses ApiId. Wrong dimension = empty results.
Metric name casingREST: 5XXError; HTTP: 5xx. Check API type before querying.
Usage plansREST API only. HTTP APIs use route-level throttling.
Latency metricsLatency = total (including APIGW overhead). IntegrationLatency = backend only.
Stage requirementMetrics require Stage dimension for per-stage accuracy.
DeploymentREST: changes require new deployment. HTTP: auto-deploy by default.

Counter-Rationalizations

ShortcutCounterWhy
"I'll just check REST APIs"Always discover both REST and HTTP APIsHTTP APIs are increasingly common; missing them gives incomplete picture
"Metrics aren't needed for health check"Always check CloudWatch metricsAPIs can return 200 while silently failing on a subset of requests
"Default stage config is fine"Audit stage config explicitlyDefaults leave execution logging, tracing, and caching disabled
"Usage plans aren't relevant"Review if REST API has external consumersUnthrottled APIs cause cascading failures under load
"The API is responding, so it's healthy"Check error rates AND latency percentilesp50 may be fine while p99 is unacceptable

Output Format

API Gateway Health Report
═══════════════════════════
REST APIs: [count] | HTTP APIs: [count]

API          Type  Stage  Latency(avg/max)  5xx(7d)  Cache  Logging  Tracing
─────────────────────────────────────────────────────────────────────────────
my-api       REST  prod   45ms/230ms        12       ON     ERROR    ON
payment-api  HTTP  $def   22ms/89ms         0        N/A    ACCESS   N/A

Throttling: Account [burst/rate] | Plans: [count]
Issues: [list of findings with severity]

Common Pitfalls

  • Endpoint types: REGIONAL, EDGE, or PRIVATE. Edge uses CloudFront automatically — don't confuse with standalone distributions.
  • API key ≠ authentication: API keys track usage/throttling only. Use authorizers (Lambda, Cognito, IAM) for auth.
  • CloudWatch statistics syntax: Use spaces not commas: --statistics Average Maximum.
  • WebSocket APIs: Use apigatewayv2 with ProtocolType=WEBSOCKET. Different metric dimensions.
  • Cross-platform date: macOS uses -v-7d, Linux uses -d "7 days ago". Scripts handle both.

References

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall