Files
skills/public/cloud-aws-api-gateway.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

674 lines
32 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>cloud-aws-api-gateway</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/cloud-aws-api-gateway.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/cloud-aws-api-gateway">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/cloud-aws-api-gateway.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>cloud-aws-api-gateway</h1><p class="lede">AWS API Gateway REST APIs, HTTP APIs, WebSocket APIs, authorization, and integration patterns</p><h1>AWS API Gateway</h1>
<p><strong>Scope</strong>: API Gateway configuration - REST vs HTTP APIs, WebSocket, authorization, CORS, throttling, integrations <strong>Lines</strong>: ~300 <strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<hr>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Building REST APIs with Lambda backend</li><li>Creating HTTP APIs for lower latency and cost</li><li>Implementing WebSocket APIs for real-time communication</li><li>Configuring API authorization (IAM, Lambda, Cognito, API keys)</li><li>Setting up CORS for cross-origin requests</li><li>Implementing API throttling and usage plans</li><li>Integrating with Lambda, HTTP endpoints, or AWS services</li><li>Troubleshooting API Gateway request/response issues</li></ul>
<h2>Core Concepts</h2>
<h3>Concept 1: REST API vs HTTP API</h3>
<p><strong>REST API</strong>:</p>
<ul><li>Full-featured, more expensive ($3.50/million requests)</li><li>API keys, usage plans, request validation</li><li>Request/response transformations</li><li>Caching support</li><li>Use for: Complex authorization, legacy systems</li></ul>
<p><strong>HTTP API</strong>:</p>
<ul><li>Simpler, cheaper ($1.00/million requests)</li><li>60% lower latency than REST APIs</li><li>JWT authorization built-in</li><li>CORS configuration simplified</li><li>Use for: Modern APIs, Lambda proxy integration</li></ul>
<pre><code class="lang-bash"># Create HTTP API (recommended for new projects)
aws apigatewayv2 create-api \
--name my-http-api \
--protocol-type HTTP \
--target arn:aws:lambda:us-east-1:123456789012:function:my-function
# Create REST API (for advanced features)
aws apigateway create-rest-api \
--name my-rest-api \
--endpoint-configuration types=REGIONAL</code></pre>
<h3>Concept 2: Lambda Proxy Integration</h3>
<p><strong>Proxy integration</strong>:</p>
<ul><li>Lambda receives full HTTP request as event</li><li>Lambda returns HTTP response format</li><li>No request/response mapping needed</li><li>Simpler configuration</li></ul>
<pre><code class="lang-python"># Lambda function for API Gateway proxy integration
import json
def lambda_handler(event, context):
&quot;&quot;&quot;
Handle API Gateway proxy integration
Event structure:
{
&#x27;httpMethod&#x27;: &#x27;GET&#x27;,
&#x27;path&#x27;: &#x27;/users/123&#x27;,
&#x27;queryStringParameters&#x27;: {&#x27;filter&#x27;: &#x27;active&#x27;},
&#x27;headers&#x27;: {&#x27;Content-Type&#x27;: &#x27;application/json&#x27;},
&#x27;body&#x27;: &#x27;{&quot;name&quot;: &quot;John&quot;}&#x27;,
&#x27;pathParameters&#x27;: {&#x27;id&#x27;: &#x27;123&#x27;},
&#x27;requestContext&#x27;: {...}
}
&quot;&quot;&quot;
# Parse request
method = event[&#x27;httpMethod&#x27;]
path = event[&#x27;path&#x27;]
body = json.loads(event.get(&#x27;body&#x27;, &#x27;{}&#x27;))
# Route request
if method == &#x27;GET&#x27; and path.startswith(&#x27;/users/&#x27;):
user_id = event[&#x27;pathParameters&#x27;][&#x27;id&#x27;]
return get_user(user_id)
elif method == &#x27;POST&#x27; and path == &#x27;/users&#x27;:
return create_user(body)
# Return 404 for unmatched routes
return {
&#x27;statusCode&#x27;: 404,
&#x27;headers&#x27;: {
&#x27;Content-Type&#x27;: &#x27;application/json&#x27;,
&#x27;Access-Control-Allow-Origin&#x27;: &#x27;*&#x27;
},
&#x27;body&#x27;: json.dumps({&#x27;error&#x27;: &#x27;Not found&#x27;})
}
def get_user(user_id):
&quot;&quot;&quot;Get user by ID&quot;&quot;&quot;
# Your logic here
user = {&#x27;id&#x27;: user_id, &#x27;name&#x27;: &#x27;John Doe&#x27;}
return {
&#x27;statusCode&#x27;: 200,
&#x27;headers&#x27;: {
&#x27;Content-Type&#x27;: &#x27;application/json&#x27;,
&#x27;Access-Control-Allow-Origin&#x27;: &#x27;*&#x27;
},
&#x27;body&#x27;: json.dumps(user)
}</code></pre>
<h3>Concept 3: WebSocket APIs</h3>
<p><strong>WebSocket use cases</strong>:</p>
<ul><li>Real-time chat applications</li><li>Live dashboards and notifications</li><li>Collaborative editing tools</li><li>Gaming backends</li></ul>
<pre><code class="lang-python">import boto3
import json
apigateway_management = None
def lambda_handler(event, context):
&quot;&quot;&quot;
Handle WebSocket events
Routes:
- $connect: Client connects
- $disconnect: Client disconnects
- sendMessage: Custom route
&quot;&quot;&quot;
route_key = event[&#x27;requestContext&#x27;][&#x27;routeKey&#x27;]
connection_id = event[&#x27;requestContext&#x27;][&#x27;connectionId&#x27;]
if route_key == &#x27;$connect&#x27;:
return handle_connect(connection_id)
elif route_key == &#x27;$disconnect&#x27;:
return handle_disconnect(connection_id)
elif route_key == &#x27;sendMessage&#x27;:
return handle_message(event, connection_id)
return {&#x27;statusCode&#x27;: 400, &#x27;body&#x27;: &#x27;Unknown route&#x27;}
def handle_connect(connection_id):
&quot;&quot;&quot;Store connection in DynamoDB&quot;&quot;&quot;
table.put_item(Item={
&#x27;connectionId&#x27;: connection_id,
&#x27;timestamp&#x27;: datetime.utcnow().isoformat()
})
return {&#x27;statusCode&#x27;: 200, &#x27;body&#x27;: &#x27;Connected&#x27;}
def handle_message(event, connection_id):
&quot;&quot;&quot;Broadcast message to all connections&quot;&quot;&quot;
global apigateway_management
# Initialize API Gateway Management API client
if not apigateway_management:
endpoint_url = f&quot;https://{event[&#x27;requestContext&#x27;][&#x27;domainName&#x27;]}/{event[&#x27;requestContext&#x27;][&#x27;stage&#x27;]}&quot;
apigateway_management = boto3.client(&#x27;apigatewaymanagementapi&#x27;, endpoint_url=endpoint_url)
# Parse message
body = json.loads(event.get(&#x27;body&#x27;, &#x27;{}&#x27;))
message = body.get(&#x27;message&#x27;, &#x27;&#x27;)
# Get all connections
response = table.scan()
connections = response[&#x27;Items&#x27;]
# Send to all connections
for conn in connections:
try:
apigateway_management.post_to_connection(
ConnectionId=conn[&#x27;connectionId&#x27;],
Data=json.dumps({&#x27;message&#x27;: message})
)
except apigateway_management.exceptions.GoneException:
# Connection no longer exists
table.delete_item(Key={&#x27;connectionId&#x27;: conn[&#x27;connectionId&#x27;]})
return {&#x27;statusCode&#x27;: 200, &#x27;body&#x27;: &#x27;Message sent&#x27;}</code></pre>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: CORS Configuration</h3>
<p><strong>When to use</strong>: Frontend apps making cross-origin requests</p>
<pre><code class="lang-bash"># HTTP API - simple CORS configuration
aws apigatewayv2 update-api \
--api-id abc123 \
--cors-configuration AllowOrigins=&quot;https://example.com&quot;,AllowMethods=&quot;GET,POST,PUT,DELETE&quot;,AllowHeaders=&quot;Content-Type,Authorization&quot;
# REST API - requires OPTIONS method and response headers
# Created via console or CloudFormation (more complex)</code></pre>
<pre><code class="lang-python"># Lambda function with CORS headers
def lambda_handler(event, context):
&quot;&quot;&quot;Return CORS headers with all responses&quot;&quot;&quot;
# Handle preflight request
if event[&#x27;httpMethod&#x27;] == &#x27;OPTIONS&#x27;:
return {
&#x27;statusCode&#x27;: 200,
&#x27;headers&#x27;: {
&#x27;Access-Control-Allow-Origin&#x27;: &#x27;https://example.com&#x27;,
&#x27;Access-Control-Allow-Methods&#x27;: &#x27;GET,POST,PUT,DELETE,OPTIONS&#x27;,
&#x27;Access-Control-Allow-Headers&#x27;: &#x27;Content-Type,Authorization&#x27;,
&#x27;Access-Control-Max-Age&#x27;: &#x27;3600&#x27;
},
&#x27;body&#x27;: &#x27;&#x27;
}
# Normal request with CORS headers
return {
&#x27;statusCode&#x27;: 200,
&#x27;headers&#x27;: {
&#x27;Content-Type&#x27;: &#x27;application/json&#x27;,
&#x27;Access-Control-Allow-Origin&#x27;: &#x27;https://example.com&#x27;
},
&#x27;body&#x27;: json.dumps({&#x27;message&#x27;: &#x27;Success&#x27;})
}</code></pre>
<h3>Pattern 2: Lambda Authorizer (Custom Authorization)</h3>
<p><strong>Use case</strong>: Custom authentication logic (API tokens, OAuth, etc.)</p>
<pre><code class="lang-python">def lambda_handler(event, context):
&quot;&quot;&quot;
Lambda authorizer for API Gateway
Event structure:
{
&#x27;type&#x27;: &#x27;REQUEST&#x27;,
&#x27;methodArn&#x27;: &#x27;arn:aws:execute-api:...&#x27;,
&#x27;headers&#x27;: {&#x27;Authorization&#x27;: &#x27;Bearer token123&#x27;}
}
&quot;&quot;&quot;
# Extract token
token = event[&#x27;headers&#x27;].get(&#x27;Authorization&#x27;, &#x27;&#x27;).replace(&#x27;Bearer &#x27;, &#x27;&#x27;)
# Validate token
user = validate_token(token)
if not user:
raise Exception(&#x27;Unauthorized&#x27;) # Returns 401
# Generate IAM policy
return {
&#x27;principalId&#x27;: user[&#x27;id&#x27;],
&#x27;policyDocument&#x27;: {
&#x27;Version&#x27;: &#x27;2012-10-17&#x27;,
&#x27;Statement&#x27;: [
{
&#x27;Action&#x27;: &#x27;execute-api:Invoke&#x27;,
&#x27;Effect&#x27;: &#x27;Allow&#x27;,
&#x27;Resource&#x27;: event[&#x27;methodArn&#x27;]
}
]
},
&#x27;context&#x27;: {
&#x27;userId&#x27;: user[&#x27;id&#x27;],
&#x27;email&#x27;: user[&#x27;email&#x27;]
}
}
def validate_token(token):
&quot;&quot;&quot;Validate JWT or API token&quot;&quot;&quot;
# Your validation logic
if token == &#x27;valid-token&#x27;:
return {&#x27;id&#x27;: &#x27;user123&#x27;, &#x27;email&#x27;: &#x27;[email protected]&#x27;}
return None</code></pre>
<pre><code class="lang-python"># Access authorizer context in Lambda function
def api_handler(event, context):
&quot;&quot;&quot;Lambda function receiving authorized request&quot;&quot;&quot;
# Access authorizer context
user_id = event[&#x27;requestContext&#x27;][&#x27;authorizer&#x27;][&#x27;userId&#x27;]
email = event[&#x27;requestContext&#x27;][&#x27;authorizer&#x27;][&#x27;email&#x27;]
return {
&#x27;statusCode&#x27;: 200,
&#x27;body&#x27;: json.dumps({
&#x27;message&#x27;: f&#x27;Hello {email}&#x27;,
&#x27;userId&#x27;: user_id
})
}</code></pre>
<h3>Pattern 3: Cognito User Pool Authorization</h3>
<p><strong>Use case</strong>: User authentication with Cognito</p>
<pre><code class="lang-bash"># Create HTTP API with Cognito authorizer
aws apigatewayv2 create-authorizer \
--api-id abc123 \
--name cognito-auth \
--authorizer-type JWT \
--identity-source &#x27;$request.header.Authorization&#x27; \
--jwt-configuration Audience=abc123,Issuer=https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abc123
# Attach to route
aws apigatewayv2 update-route \
--api-id abc123 \
--route-id xyz789 \
--authorization-type JWT \
--authorizer-id auth123</code></pre>
<pre><code class="lang-python"># Lambda function with Cognito authorization
def lambda_handler(event, context):
&quot;&quot;&quot;Access Cognito claims from request context&quot;&quot;&quot;
# Cognito user claims available in request context
claims = event[&#x27;requestContext&#x27;][&#x27;authorizer&#x27;][&#x27;claims&#x27;]
user_id = claims[&#x27;sub&#x27;]
email = claims[&#x27;email&#x27;]
username = claims[&#x27;cognito:username&#x27;]
return {
&#x27;statusCode&#x27;: 200,
&#x27;body&#x27;: json.dumps({
&#x27;userId&#x27;: user_id,
&#x27;email&#x27;: email,
&#x27;username&#x27;: username
})
}</code></pre>
<h3>Pattern 4: Throttling and Usage Plans</h3>
<p><strong>Use case</strong>: Rate limiting, quotas, API monetization</p>
<pre><code class="lang-bash"># Create usage plan with throttling
aws apigateway create-usage-plan \
--name basic-plan \
--throttle burstLimit=100,rateLimit=50 \
--quota limit=10000,period=MONTH
# Create API key
aws apigateway create-api-key \
--name customer-key \
--enabled
# Associate key with usage plan
aws apigateway create-usage-plan-key \
--usage-plan-id plan123 \
--key-id key123 \
--key-type API_KEY</code></pre>
<pre><code class="lang-python"># Lambda function - API key available in request context
def lambda_handler(event, context):
&quot;&quot;&quot;Check API key usage&quot;&quot;&quot;
# API key ID available if request includes x-api-key header
api_key_id = event[&#x27;requestContext&#x27;].get(&#x27;identity&#x27;, {}).get(&#x27;apiKeyId&#x27;)
if api_key_id:
print(f&quot;Request from API key: {api_key_id}&quot;)
return {
&#x27;statusCode&#x27;: 200,
&#x27;body&#x27;: json.dumps({&#x27;message&#x27;: &#x27;Success&#x27;})
}</code></pre>
<h3>Pattern 5: Request Validation</h3>
<p><strong>Use case</strong>: Validate request schema before Lambda invocation</p>
<pre><code class="lang-json">// Request body JSON schema
{
&quot;$schema&quot;: &quot;http://json-schema.org/draft-04/schema#&quot;,
&quot;type&quot;: &quot;object&quot;,
&quot;properties&quot;: {
&quot;name&quot;: {&quot;type&quot;: &quot;string&quot;, &quot;minLength&quot;: 1},
&quot;email&quot;: {&quot;type&quot;: &quot;string&quot;, &quot;format&quot;: &quot;email&quot;},
&quot;age&quot;: {&quot;type&quot;: &quot;integer&quot;, &quot;minimum&quot;: 0}
},
&quot;required&quot;: [&quot;name&quot;, &quot;email&quot;]
}</code></pre>
<pre><code class="lang-bash"># Create model
aws apigateway create-model \
--rest-api-id abc123 \
--name UserModel \
--content-type application/json \
--schema file://user-schema.json
# Create request validator
aws apigateway create-request-validator \
--rest-api-id abc123 \
--name body-validator \
--validate-request-body</code></pre>
<h3>Pattern 6: HTTP Endpoint Integration (No Lambda)</h3>
<p><strong>Use case</strong>: Proxy to existing HTTP backend</p>
<pre><code class="lang-bash"># Create HTTP API with HTTP proxy integration
aws apigatewayv2 create-integration \
--api-id abc123 \
--integration-type HTTP_PROXY \
--integration-uri https://api.example.com/{proxy} \
--integration-method ANY \
--payload-format-version 1.0
# Create route
aws apigatewayv2 create-route \
--api-id abc123 \
--route-key &#x27;ANY /api/{proxy+}&#x27; \
--target integrations/integration123</code></pre>
<p><strong>Benefits</strong>:</p>
<ul><li>No Lambda invocation cost</li><li>Direct proxy to backend</li><li>API Gateway adds throttling, caching, authorization</li></ul>
<hr>
<h2>Quick Reference</h2>
<h3>API Types Comparison</h3>
<p>| Feature | HTTP API | REST API | WebSocket API | |---------|----------|----------|---------------| | <strong>Price</strong> | $1.00/M requests | $3.50/M requests | $1.00/M messages | | <strong>Latency</strong> | Lower | Higher | N/A | | <strong>CORS</strong> | Simple config | Manual setup | N/A | | <strong>Caching</strong> | No | Yes | No | | <strong>Usage plans</strong> | No | Yes | No | | <strong>Request validation</strong> | No | Yes | No | | <strong>Best for</strong> | Modern APIs | Complex APIs | Real-time |</p>
<h3>Authorization Methods</h3>
<pre><code>Method | Use Case | Complexity
--------------------|-----------------------------------|------------
IAM | AWS service-to-service | Medium
Lambda Authorizer | Custom authentication logic | High
Cognito | User authentication (JWT) | Medium
API Key | Simple client identification | Low</code></pre>
<h3>Key Guidelines</h3>
<pre><code>✅ DO: Use HTTP API for new projects (lower cost, latency)
✅ DO: Use Lambda proxy integration (simpler than custom)
✅ DO: Configure CORS for cross-origin requests
✅ DO: Use Cognito for user authentication
✅ DO: Set throttling limits to protect backend
✅ DO: Enable CloudWatch logging for troubleshooting
❌ DON&#x27;T: Use REST API unless you need advanced features
❌ DON&#x27;T: Hardcode CORS origins (use environment variables)
❌ DON&#x27;T: Skip throttling (risk backend overload)
❌ DON&#x27;T: Return large responses (6 MB limit)
❌ DON&#x27;T: Use API keys for authentication (use Cognito/Lambda authorizer)</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<h3>Critical Violations</h3>
<pre><code class="lang-python"># ❌ NEVER: Hardcode CORS origins in production
def lambda_handler(event, context):
return {
&#x27;statusCode&#x27;: 200,
&#x27;headers&#x27;: {
&#x27;Access-Control-Allow-Origin&#x27;: &#x27;*&#x27; # Allows any origin
},
&#x27;body&#x27;: json.dumps({&#x27;data&#x27;: &#x27;sensitive&#x27;})
}
# ✅ CORRECT: Use environment variable or whitelist
ALLOWED_ORIGINS = os.environ.get(&#x27;ALLOWED_ORIGINS&#x27;, &#x27;&#x27;).split(&#x27;,&#x27;)
def lambda_handler(event, context):
origin = event[&#x27;headers&#x27;].get(&#x27;origin&#x27;, &#x27;&#x27;)
# Check origin
if origin in ALLOWED_ORIGINS:
cors_origin = origin
else:
cors_origin = ALLOWED_ORIGINS[0] # Default
return {
&#x27;statusCode&#x27;: 200,
&#x27;headers&#x27;: {
&#x27;Access-Control-Allow-Origin&#x27;: cors_origin
},
&#x27;body&#x27;: json.dumps({&#x27;data&#x27;: &#x27;sensitive&#x27;})
}</code></pre>
<p>❌ <strong>Allow-Origin: </strong>*: Exposes APIs to any website, security risk for authenticated APIs</p>
<p>✅ <strong>Correct approach</strong>: Whitelist specific origins, validate origin header</p>
<h3>Common Mistakes</h3>
<pre><code class="lang-python"># ❌ Don&#x27;t skip error handling
def lambda_handler(event, context):
user = get_user(event[&#x27;pathParameters&#x27;][&#x27;id&#x27;]) # May not exist
return {&#x27;statusCode&#x27;: 200, &#x27;body&#x27;: json.dumps(user)}
# ✅ Correct: Handle errors and return proper status codes
def lambda_handler(event, context):
try:
user_id = event.get(&#x27;pathParameters&#x27;, {}).get(&#x27;id&#x27;)
if not user_id:
return {
&#x27;statusCode&#x27;: 400,
&#x27;body&#x27;: json.dumps({&#x27;error&#x27;: &#x27;Missing user ID&#x27;})
}
user = get_user(user_id)
if not user:
return {
&#x27;statusCode&#x27;: 404,
&#x27;body&#x27;: json.dumps({&#x27;error&#x27;: &#x27;User not found&#x27;})
}
return {
&#x27;statusCode&#x27;: 200,
&#x27;body&#x27;: json.dumps(user)
}
except Exception as e:
print(f&quot;Error: {str(e)}&quot;)
return {
&#x27;statusCode&#x27;: 500,
&#x27;body&#x27;: json.dumps({&#x27;error&#x27;: &#x27;Internal server error&#x27;})
}</code></pre>
<p>❌ <strong>Missing error handling</strong>: Returns 200 even for errors, confuses clients</p>
<p>✅ <strong>Better</strong>: Return appropriate HTTP status codes (400, 404, 500)</p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>aws-lambda-functions.md</code> - Lambda function development for API Gateway backends</li><li><code>aws-iam-security.md</code> - IAM policies for API Gateway authorization</li><li><code>aws-networking.md</code> - CloudFront integration for API caching and global distribution</li><li><code>infrastructure/aws-serverless.md</code> - Complete serverless API architecture patterns</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/cloud-aws-api-gateway.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>