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

api-gateway skill

safe

/skills/api-gateway

This skill helps you design, configure, and troubleshoot AWS API Gateway setups across REST, HTTP, and WebSocket APIs.

npx playbooks add skill itsmostafa/aws-agent-skills --skill api-gateway

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

8.7 KB

---
name: api-gateway
description: 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.
last_updated: "2026-01-07"
doc_source: https://docs.aws.amazon.com/apigateway/latest/developerguide/
---

# 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](#core-concepts)
- [Common Patterns](#common-patterns)
- [CLI Reference](#cli-reference)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)
- [References](#references)

## Core Concepts

### API Types

| Type | Description | Use Case |
|------|-------------|----------|
| **HTTP API** | Low-latency, cost-effective | Simple APIs, Lambda proxy |
| **REST API** | Full-featured, more control | Complex APIs, transformation |
| **WebSocket API** | Bidirectional communication | Real-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

| Type | Description |
|------|-------------|
| **Lambda Proxy** | Pass-through to Lambda (recommended) |
| **Lambda Custom** | Transform request/response |
| **HTTP Proxy** | Pass-through to HTTP endpoint |
| **AWS Service** | Direct integration with AWS services |
| **Mock** | Return static response |

## Common Patterns

### Create HTTP API with Lambda

**AWS CLI:**

```bash
# 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:**

```yaml
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

```bash
# 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

```python
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:**

```bash
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:**

```bash
# 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)

```bash
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)

| Command | Description |
|---------|-------------|
| `aws apigatewayv2 create-api` | Create API |
| `aws apigatewayv2 get-apis` | List APIs |
| `aws apigatewayv2 create-route` | Create route |
| `aws apigatewayv2 create-integration` | Create integration |
| `aws apigatewayv2 create-stage` | Create stage |
| `aws apigatewayv2 create-authorizer` | Create authorizer |

### REST API (apigateway)

| Command | Description |
|---------|-------------|
| `aws apigateway create-rest-api` | Create API |
| `aws apigateway get-rest-apis` | List APIs |
| `aws apigateway create-resource` | Create resource |
| `aws apigateway put-method` | Create method |
| `aws apigateway put-integration` | Create integration |
| `aws apigateway create-deployment` | Deploy 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:**

```bash
# 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:**

```python
# 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

- [API Gateway Developer Guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/)
- [API Gateway REST API Reference](https://docs.aws.amazon.com/apigateway/latest/api/)
- [API Gateway CLI Reference](https://docs.aws.amazon.com/cli/latest/reference/apigateway/)
- [boto3 API Gateway](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigateway.html)

Overview

This skill provides practical guidance and commands for managing AWS API Gateway (REST, HTTP, and WebSocket). It helps you create APIs, configure integrations and authorizers, manage stages and CORS, implement rate limiting, and troubleshoot common API issues. The focus is on actionable CLI patterns, deployment tips, and operational best practices.

How this skill works

The skill documents core API Gateway concepts (API types, resources, methods, integrations, and stages) and maps them to CLI and infrastructure-as-code examples. It includes step-by-step AWS CLI commands for creating HTTP and REST APIs, wiring Lambda integrations, enabling CORS, and setting up JWT authorizers. Troubleshooting sections explain common error causes and diagnostic CLI checks.

When to use it

When creating a new public or internal HTTP/REST API backed by Lambda or HTTP endpoints.
When configuring authorization (JWT, Lambda authorizers) and CORS for browser clients.
When deploying stages, enabling canaries, or managing stage settings like throttling and caching.
When implementing rate limiting, API keys, or WAF protections to secure and protect backends.
When troubleshooting 403/502/504/CORS errors and validating integration responses and logs.

Best practices

Prefer HTTP APIs for simple, low-latency workloads; use REST APIs when you need advanced transformations or features.
Enable access logging, CloudWatch monitoring, and set appropriate throttling and caching to protect backends.
Use JWT or other authorizers for authentication and API keys only for usage plans and rate limiting, not as auth.
Use regional endpoints unless you require global distribution; enable HTTPS and WAF for public APIs.
Adopt canary deployments and stage variables for safer updates and gradual rollouts.

Example use cases

Create a low-cost HTTP API that proxies requests to a Lambda function for a microservice.
Deploy a REST API with Lambda proxy integration and enable response transformations and caching.
Add JWT authorization using Cognito or an external provider for authenticated mobile and web clients.
Configure CORS and preflight OPTIONS for a single-page app calling your API from a browser.
Troubleshoot a 502 error by validating the Lambda response format and checking CloudWatch logs.

FAQ

Which API type should I choose: HTTP or REST?

Use HTTP APIs for most simple services because they are cheaper and lower latency. Choose REST APIs when you need advanced features like complex transformation, fine-grained request/response mapping, or legacy integrations.

Why am I getting 502 Bad Gateway from API Gateway?

Common causes are Lambda errors, incorrect integration URIs, or invalid response format. Verify the backend is healthy and that Lambda returns the required statusCode/headers/body shape.