Skip to content

itsmostafa/aws-agent-skills / skills/api-gateway

api-gateway

Verified

AWS API Gateway for REST and HTTP API management. Use when creating APIs, configuring integrations, setting up authorization, managing stages, implementing rate limiting, or troubleshooting API issues.

AWS API Gateway

Amazon API Gateway is a fully managed service for creating, publishing, and securing APIs at any scale. Supports REST APIs, HTTP APIs, and WebSocket APIs.

Table of Contents

Core Concepts

API Types

TypeDescriptionUse Case
HTTP APILow-latency, cost-effectiveSimple APIs, Lambda proxy
REST APIFull-featured, more controlComplex APIs, transformation
WebSocket APIBidirectional communicationReal-time apps, chat

Key Components

  • Resources: URL paths (/users, /orders/{id})
  • Methods: HTTP verbs (GET, POST, PUT, DELETE)
  • Integrations: Backend connections (Lambda, HTTP, AWS services)
  • Stages: Deployment environments (dev, prod)

Integration Types

TypeDescription
Lambda ProxyPass-through to Lambda (recommended)
Lambda CustomTransform request/response
HTTP ProxyPass-through to HTTP endpoint
AWS ServiceDirect integration with AWS services
MockReturn static response

Common Patterns

Create HTTP API with Lambda

AWS CLI:

# Create HTTP API
aws apigatewayv2 create-api \
  --name my-api \
  --protocol-type HTTP \
  --target arn:aws:lambda:us-east-1:123456789012:function:MyFunction

# Get API endpoint
aws apigatewayv2 get-api --api-id abc123 --query 'ApiEndpoint'

SAM Template:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Resources:
  MyApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: prod

  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: app.handler
      Runtime: python3.12
      Events:
        ApiEvent:
          Type: HttpApi
          Properties:
            ApiId: !Ref MyApi
            Path: /items
            Method: GET

Create REST API with Lambda Proxy

# Create REST API
aws apigateway create-rest-api \
  --name my-rest-api \
  --endpoint-configuration types=REGIONAL

API_ID=abc123

# Get root resource ID
ROOT_ID=$(aws apigateway get-resources --rest-api-id $API_ID --query 'items[0].id' --output text)

# Create resource
aws apigateway create-resource \
  --rest-api-id $API_ID \
  --parent-id $ROOT_ID \
  --path-part items

RESOURCE_ID=xyz789

# Create method
aws apigateway put-method \
  --rest-api-id $API_ID \
  --resource-id $RESOURCE_ID \
  --http-method GET \
  --authorization-type NONE

# Create Lambda integration
aws apigateway put-integration \
  --rest-api-id $API_ID \
  --resource-id $RESOURCE_ID \
  --http-method GET \
  --type AWS_PROXY \
  --integration-http-method POST \
  --uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:MyFunction/invocations

# Deploy to stage
aws apigateway create-deployment \
  --rest-api-id $API_ID \
  --stage-name prod

Lambda Handler for API Gateway

import json

def handler(event, context):
    # HTTP API event
    http_method = event.get('requestContext', {}).get('http', {}).get('method')
    path = event.get('rawPath', '')
    query_params = event.get('queryStringParameters', {})
    body = event.get('body', '')

    if body and event.get('isBase64Encoded'):
        import base64
        body = base64.b64decode(body).decode('utf-8')

    # Process request
    response_body = {'message': 'Success', 'path': path}

    return {
        'statusCode': 200,
        'headers': {
            'Content-Type': 'application/json'
        },
        'body': json.dumps(response_body)
    }

Configure CORS

HTTP API:

aws apigatewayv2 update-api \
  --api-id abc123 \
  --cors-configuration '{
    "AllowOrigins": ["https://example.com"],
    "AllowMethods": ["GET", "POST", "PUT", "DELETE"],
    "AllowHeaders": ["Content-Type", "Authorization"],
    "MaxAge": 86400
  }'

REST API:

# Enable CORS on resource
aws apigateway put-method \
  --rest-api-id $API_ID \
  --resource-id $RESOURCE_ID \
  --http-method OPTIONS \
  --authorization-type NONE

aws apigateway put-integration \
  --rest-api-id $API_ID \
  --resource-id $RESOURCE_ID \
  --http-method OPTIONS \
  --type MOCK \
  --request-templates '{"application/json": "{\"statusCode\": 200}"}'

aws apigateway put-method-response \
  --rest-api-id $API_ID \
  --resource-id $RESOURCE_ID \
  --http-method OPTIONS \
  --status-code 200 \
  --response-parameters '{
    "method.response.header.Access-Control-Allow-Headers": true,
    "method.response.header.Access-Control-Allow-Methods": true,
    "method.response.header.Access-Control-Allow-Origin": true
  }'

aws apigateway put-integration-response \
  --rest-api-id $API_ID \
  --resource-id $RESOURCE_ID \
  --http-method OPTIONS \
  --status-code 200 \
  --response-parameters '{
    "method.response.header.Access-Control-Allow-Headers": "'\''Content-Type,Authorization'\''",
    "method.response.header.Access-Control-Allow-Methods": "'\''GET,POST,PUT,DELETE,OPTIONS'\''",
    "method.response.header.Access-Control-Allow-Origin": "'\''*'\''"
  }'

JWT Authorization (HTTP API)

aws apigatewayv2 create-authorizer \
  --api-id abc123 \
  --name jwt-authorizer \
  --authorizer-type JWT \
  --identity-source '$request.header.Authorization' \
  --jwt-configuration '{
    "Issuer": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abc123",
    "Audience": ["client-id"]
  }'

CLI Reference

HTTP API (apigatewayv2)

CommandDescription
aws apigatewayv2 create-apiCreate API
aws apigatewayv2 get-apisList APIs
aws apigatewayv2 create-routeCreate route
aws apigatewayv2 create-integrationCreate integration
aws apigatewayv2 create-stageCreate stage
aws apigatewayv2 create-authorizerCreate authorizer

REST API (apigateway)

CommandDescription
aws apigateway create-rest-apiCreate API
aws apigateway get-rest-apisList APIs
aws apigateway create-resourceCreate resource
aws apigateway put-methodCreate method
aws apigateway put-integrationCreate integration
aws apigateway create-deploymentDeploy API

Best Practices

Performance

  • Use HTTP APIs for simple use cases (70% cheaper, lower latency)
  • Enable caching for REST APIs
  • Use regional endpoints unless global distribution needed
  • Implement pagination for list endpoints

Security

  • Use authorization on all endpoints
  • Enable WAF for REST APIs
  • Use API keys for rate limiting (not authentication)
  • Enable access logging
  • Use HTTPS only

Reliability

  • Set up throttling to protect backends
  • Configure timeout appropriately
  • Use canary deployments for updates
  • Monitor with CloudWatch

Troubleshooting

403 Forbidden

Causes:

  • Missing authorization
  • Invalid API key
  • WAF blocking
  • Resource policy denying

Debug:

# Check API key
aws apigateway get-api-key --api-key abc123 --include-value

# Check authorizer
aws apigatewayv2 get-authorizer --api-id abc123 --authorizer-id xyz789

502 Bad Gateway

Causes:

  • Lambda error
  • Integration timeout
  • Invalid response format

Lambda response format:

# Correct format
return {
    'statusCode': 200,
    'headers': {'Content-Type': 'application/json'},
    'body': json.dumps({'message': 'success'})
}

# Wrong - missing statusCode
return {'message': 'success'}

504 Gateway Timeout

Causes:

  • Backend timeout (Lambda max 29 seconds for REST API)
  • Integration timeout too short

Solutions:

  • Increase Lambda timeout
  • Use async processing for long operations
  • Increase integration timeout (max 29s for REST, 30s for HTTP)

CORS Errors

Debug:

  • Check OPTIONS method exists
  • Verify headers in response
  • Check origin matches allowed origins

References

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated 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: 196kUpdated 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: 118kUpdated 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