mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
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]>
674 lines
32 KiB
HTML
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):
|
|
"""
|
|
Handle API Gateway proxy integration
|
|
|
|
Event structure:
|
|
{
|
|
'httpMethod': 'GET',
|
|
'path': '/users/123',
|
|
'queryStringParameters': {'filter': 'active'},
|
|
'headers': {'Content-Type': 'application/json'},
|
|
'body': '{"name": "John"}',
|
|
'pathParameters': {'id': '123'},
|
|
'requestContext': {...}
|
|
}
|
|
"""
|
|
|
|
# Parse request
|
|
method = event['httpMethod']
|
|
path = event['path']
|
|
body = json.loads(event.get('body', '{}'))
|
|
|
|
# Route request
|
|
if method == 'GET' and path.startswith('/users/'):
|
|
user_id = event['pathParameters']['id']
|
|
return get_user(user_id)
|
|
elif method == 'POST' and path == '/users':
|
|
return create_user(body)
|
|
|
|
# Return 404 for unmatched routes
|
|
return {
|
|
'statusCode': 404,
|
|
'headers': {
|
|
'Content-Type': 'application/json',
|
|
'Access-Control-Allow-Origin': '*'
|
|
},
|
|
'body': json.dumps({'error': 'Not found'})
|
|
}
|
|
|
|
def get_user(user_id):
|
|
"""Get user by ID"""
|
|
# Your logic here
|
|
user = {'id': user_id, 'name': 'John Doe'}
|
|
|
|
return {
|
|
'statusCode': 200,
|
|
'headers': {
|
|
'Content-Type': 'application/json',
|
|
'Access-Control-Allow-Origin': '*'
|
|
},
|
|
'body': 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):
|
|
"""
|
|
Handle WebSocket events
|
|
|
|
Routes:
|
|
- $connect: Client connects
|
|
- $disconnect: Client disconnects
|
|
- sendMessage: Custom route
|
|
"""
|
|
|
|
route_key = event['requestContext']['routeKey']
|
|
connection_id = event['requestContext']['connectionId']
|
|
|
|
if route_key == '$connect':
|
|
return handle_connect(connection_id)
|
|
elif route_key == '$disconnect':
|
|
return handle_disconnect(connection_id)
|
|
elif route_key == 'sendMessage':
|
|
return handle_message(event, connection_id)
|
|
|
|
return {'statusCode': 400, 'body': 'Unknown route'}
|
|
|
|
def handle_connect(connection_id):
|
|
"""Store connection in DynamoDB"""
|
|
table.put_item(Item={
|
|
'connectionId': connection_id,
|
|
'timestamp': datetime.utcnow().isoformat()
|
|
})
|
|
return {'statusCode': 200, 'body': 'Connected'}
|
|
|
|
def handle_message(event, connection_id):
|
|
"""Broadcast message to all connections"""
|
|
global apigateway_management
|
|
|
|
# Initialize API Gateway Management API client
|
|
if not apigateway_management:
|
|
endpoint_url = f"https://{event['requestContext']['domainName']}/{event['requestContext']['stage']}"
|
|
apigateway_management = boto3.client('apigatewaymanagementapi', endpoint_url=endpoint_url)
|
|
|
|
# Parse message
|
|
body = json.loads(event.get('body', '{}'))
|
|
message = body.get('message', '')
|
|
|
|
# Get all connections
|
|
response = table.scan()
|
|
connections = response['Items']
|
|
|
|
# Send to all connections
|
|
for conn in connections:
|
|
try:
|
|
apigateway_management.post_to_connection(
|
|
ConnectionId=conn['connectionId'],
|
|
Data=json.dumps({'message': message})
|
|
)
|
|
except apigateway_management.exceptions.GoneException:
|
|
# Connection no longer exists
|
|
table.delete_item(Key={'connectionId': conn['connectionId']})
|
|
|
|
return {'statusCode': 200, 'body': 'Message sent'}</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="https://example.com",AllowMethods="GET,POST,PUT,DELETE",AllowHeaders="Content-Type,Authorization"
|
|
|
|
# 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):
|
|
"""Return CORS headers with all responses"""
|
|
|
|
# Handle preflight request
|
|
if event['httpMethod'] == 'OPTIONS':
|
|
return {
|
|
'statusCode': 200,
|
|
'headers': {
|
|
'Access-Control-Allow-Origin': 'https://example.com',
|
|
'Access-Control-Allow-Methods': 'GET,POST,PUT,DELETE,OPTIONS',
|
|
'Access-Control-Allow-Headers': 'Content-Type,Authorization',
|
|
'Access-Control-Max-Age': '3600'
|
|
},
|
|
'body': ''
|
|
}
|
|
|
|
# Normal request with CORS headers
|
|
return {
|
|
'statusCode': 200,
|
|
'headers': {
|
|
'Content-Type': 'application/json',
|
|
'Access-Control-Allow-Origin': 'https://example.com'
|
|
},
|
|
'body': json.dumps({'message': 'Success'})
|
|
}</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):
|
|
"""
|
|
Lambda authorizer for API Gateway
|
|
|
|
Event structure:
|
|
{
|
|
'type': 'REQUEST',
|
|
'methodArn': 'arn:aws:execute-api:...',
|
|
'headers': {'Authorization': 'Bearer token123'}
|
|
}
|
|
"""
|
|
|
|
# Extract token
|
|
token = event['headers'].get('Authorization', '').replace('Bearer ', '')
|
|
|
|
# Validate token
|
|
user = validate_token(token)
|
|
|
|
if not user:
|
|
raise Exception('Unauthorized') # Returns 401
|
|
|
|
# Generate IAM policy
|
|
return {
|
|
'principalId': user['id'],
|
|
'policyDocument': {
|
|
'Version': '2012-10-17',
|
|
'Statement': [
|
|
{
|
|
'Action': 'execute-api:Invoke',
|
|
'Effect': 'Allow',
|
|
'Resource': event['methodArn']
|
|
}
|
|
]
|
|
},
|
|
'context': {
|
|
'userId': user['id'],
|
|
'email': user['email']
|
|
}
|
|
}
|
|
|
|
def validate_token(token):
|
|
"""Validate JWT or API token"""
|
|
# Your validation logic
|
|
if token == 'valid-token':
|
|
return {'id': 'user123', 'email': '[email protected]'}
|
|
return None</code></pre>
|
|
<pre><code class="lang-python"># Access authorizer context in Lambda function
|
|
def api_handler(event, context):
|
|
"""Lambda function receiving authorized request"""
|
|
|
|
# Access authorizer context
|
|
user_id = event['requestContext']['authorizer']['userId']
|
|
email = event['requestContext']['authorizer']['email']
|
|
|
|
return {
|
|
'statusCode': 200,
|
|
'body': json.dumps({
|
|
'message': f'Hello {email}',
|
|
'userId': 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 '$request.header.Authorization' \
|
|
--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):
|
|
"""Access Cognito claims from request context"""
|
|
|
|
# Cognito user claims available in request context
|
|
claims = event['requestContext']['authorizer']['claims']
|
|
|
|
user_id = claims['sub']
|
|
email = claims['email']
|
|
username = claims['cognito:username']
|
|
|
|
return {
|
|
'statusCode': 200,
|
|
'body': json.dumps({
|
|
'userId': user_id,
|
|
'email': email,
|
|
'username': 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):
|
|
"""Check API key usage"""
|
|
|
|
# API key ID available if request includes x-api-key header
|
|
api_key_id = event['requestContext'].get('identity', {}).get('apiKeyId')
|
|
|
|
if api_key_id:
|
|
print(f"Request from API key: {api_key_id}")
|
|
|
|
return {
|
|
'statusCode': 200,
|
|
'body': json.dumps({'message': 'Success'})
|
|
}</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
|
|
{
|
|
"$schema": "http://json-schema.org/draft-04/schema#",
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {"type": "string", "minLength": 1},
|
|
"email": {"type": "string", "format": "email"},
|
|
"age": {"type": "integer", "minimum": 0}
|
|
},
|
|
"required": ["name", "email"]
|
|
}</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 'ANY /api/{proxy+}' \
|
|
--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'T: Use REST API unless you need advanced features
|
|
❌ DON'T: Hardcode CORS origins (use environment variables)
|
|
❌ DON'T: Skip throttling (risk backend overload)
|
|
❌ DON'T: Return large responses (6 MB limit)
|
|
❌ DON'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 {
|
|
'statusCode': 200,
|
|
'headers': {
|
|
'Access-Control-Allow-Origin': '*' # Allows any origin
|
|
},
|
|
'body': json.dumps({'data': 'sensitive'})
|
|
}
|
|
|
|
# ✅ CORRECT: Use environment variable or whitelist
|
|
ALLOWED_ORIGINS = os.environ.get('ALLOWED_ORIGINS', '').split(',')
|
|
|
|
def lambda_handler(event, context):
|
|
origin = event['headers'].get('origin', '')
|
|
|
|
# Check origin
|
|
if origin in ALLOWED_ORIGINS:
|
|
cors_origin = origin
|
|
else:
|
|
cors_origin = ALLOWED_ORIGINS[0] # Default
|
|
|
|
return {
|
|
'statusCode': 200,
|
|
'headers': {
|
|
'Access-Control-Allow-Origin': cors_origin
|
|
},
|
|
'body': json.dumps({'data': 'sensitive'})
|
|
}</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't skip error handling
|
|
def lambda_handler(event, context):
|
|
user = get_user(event['pathParameters']['id']) # May not exist
|
|
return {'statusCode': 200, 'body': json.dumps(user)}
|
|
|
|
# ✅ Correct: Handle errors and return proper status codes
|
|
def lambda_handler(event, context):
|
|
try:
|
|
user_id = event.get('pathParameters', {}).get('id')
|
|
|
|
if not user_id:
|
|
return {
|
|
'statusCode': 400,
|
|
'body': json.dumps({'error': 'Missing user ID'})
|
|
}
|
|
|
|
user = get_user(user_id)
|
|
|
|
if not user:
|
|
return {
|
|
'statusCode': 404,
|
|
'body': json.dumps({'error': 'User not found'})
|
|
}
|
|
|
|
return {
|
|
'statusCode': 200,
|
|
'body': json.dumps(user)
|
|
}
|
|
|
|
except Exception as e:
|
|
print(f"Error: {str(e)}")
|
|
return {
|
|
'statusCode': 500,
|
|
'body': json.dumps({'error': 'Internal server error'})
|
|
}</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> |