Amazon API Gateway supports multiple types of APIs, each designed to support different protocols and use cases. The main types are HTTP API, REST API, and WebSocket API. Here’s an overview of each, with examples and usage to illustrate their differences.

1. HTTP API (HTTP/1.1)

Amazon API Gateway HTTP APIs are lightweight APIs designed for HTTP-based interactions and are ideal for simple, stateless, and high-performance applications.

Characteristics:

• HTTP/1.1 protocol-based.
• Supports stateless request-response cycles.
• Lower latency and lower cost compared to REST API in API Gateway.
• Supports basic integrations like AWS Lambda and HTTP backends.
• Supports JWT authorizers for token-based authorization (e.g., OAuth 2.0).

Usage Scenarios:

• Microservices: Best for creating APIs to handle stateless microservices.
• Web and Mobile Applications: For serving content, especially if needing to communicate with a backend service or Lambda function.
• Simple Proxy Services: Quick integration with HTTP-based backends.

Example:
To create a simple HTTP API in Amazon API Gateway, here’s what you might configure:

• Method: GET /hello
• Integration: AWS Lambda function sayHelloLambda

aws apigatewayv2 create-api \
    --name MyHttpApi \
    --protocol-type HTTP

In this example, when a client makes a GET request to /hello, API Gateway forwards the request to the Lambda function sayHelloLambda, which processes the request and returns a response.

2. REST API (Representational State Transfer)

Amazon API Gateway REST APIs are fully-managed RESTful APIs that support HTTP/1.1 and are built to handle RESTful CRUD operations (Create, Read, Update, Delete). REST APIs on API Gateway provide comprehensive features like fine-grained control over authorization, throttling, monitoring, and caching.

Characteristics:

• Based on REST architecture and HTTP/1.1.
• Supports resource-based permissions, API keys, usage plans, and stages (development, production, etc.).
• Has fine-grained control over each HTTP method (GET, POST, PUT, DELETE).
• Supports multiple authorization mechanisms (e.g., IAM, Cognito User Pools, custom Lambda authorizers).
• Provides API caching to improve performance for frequent requests.

Usage Scenarios:

• Complex APIs: Best for applications with complex API operations and high customization requirements.
• Enterprise-grade Applications: When you need features like caching, throttling, usage plans, and custom authorizers.
• RESTful Microservices: Suitable for implementing RESTful microservices that require resource-oriented APIs.

Example:
Creating a REST API in Amazon API Gateway for managing a resource (e.g., items) might look like this:

• Method: POST /items (to create an item), GET /items/{id} (to read an item)
• Integration: AWS Lambda function manageItemsLambda

aws apigateway create-rest-api \
    --name MyRestApi \
    --description "API for managing items"

In this example:

• A POST request to /items calls the manageItemsLambda to create an item.
• A GET request to /items/{id} retrieves a specific item by ID. REST APIs provide extensive configuration capabilities, making them more flexible for complex APIs but at a higher cost and with slightly higher latency compared to HTTP APIs.

3. WebSocket API

Amazon API Gateway WebSocket APIs are designed to support real-time, bidirectional communication between clients and servers. WebSocket APIs are ideal for applications that require instantaneous updates and persistent connections.

Characteristics:

• Uses the WebSocket protocol instead of HTTP.
• Supports persistent connections, where the server can push messages to connected clients.
• Designed for real-time, event-driven applications.
• Requires a connection management strategy (API Gateway handles connection IDs, but you manage your state).
• Limited to specific integration types like AWS Lambda, HTTP, and VPC Links.

Usage Scenarios:

• Real-time Applications: Great for chat applications, gaming, notifications, and IoT use cases.
• Collaborative Tools: Collaborative document editing or real-time dashboards.
• Financial Applications: For live updates of stock prices, cryptocurrency prices, etc.

Example:
A WebSocket API setup for a simple chat application might look like this:

Route: $connect (when a user connects), $disconnect (when a user disconnects), sendMessage (to send a message).
Integration: AWS Lambda function chatHandlerLambda

aws apigatewayv2 create-api \
    --name MyWebSocketApi \
    --protocol-type WEBSOCKET \
    --route-selection-expression "$request.body.action"

In this example:

• When a client connects, API Gateway invokes the chatHandlerLambda for the $connect route.
• Messages sent by clients are routed to sendMessage, where chatHandlerLambda processes and broadcasts messages to connected clients. WebSocket APIs are designed for real-time, interactive applications where users expect immediate feedback or interaction with the server.

Summary Table of HTTP API, REST API, and WebSocket API

Choosing Between HTTP, REST, and WebSocket API in API Gateway

Use HTTP API when:

• You need a simple, stateless API with lower latency and cost.
• JWT-based authorization (like OAuth 2.0) is sufficient.
• The API doesn’t require complex configurations, like caching, custom authorizers, or stages.

Use REST API when:

• You need a full-featured API with fine-grained control over configurations.
• Caching, throttling, custom authorizers, and usage plans are necessary.
• The API needs to support complex authorization requirements, like API keys or Cognito integration.

Use WebSocket API when:

• Your application requires real-time, bidirectional communication.
• A persistent connection between client and server is needed.
• It’s a use case such as a chat app, live notifications, real-time stock prices, etc.
• These API types enable you to build and scale various application types on AWS, each optimized for different communication patterns and application needs.

Types of Amazon REST Api

1. Regional REST API
A Regional REST API is deployed in a specific AWS region and intended for use within that region or nearby regions. This type of API doesn’t use CloudFront for global distribution but provides flexibility in deploying CloudFront as needed.

Characteristics:

• Region-Specific: Deployed and accessible in a specific AWS region.
• Low Latency for Local Clients: Best suited for clients close to the region where the API is deployed.
• Customizable Distribution: Allows you to attach a custom CloudFront distribution if needed for global access.
• Direct Access: Accessed directly through the regional endpoint without caching or distribution across AWS locations.

Use Cases:

• Region-Specific Applications: When you want to limit the API to a specific region or for applications serving a geographically close user base.
• Custom CDN Requirements: When you need more control over global distribution, caching, or SSL certificates through a custom CloudFront distribution.

2. Edge-Optimized REST API
An Edge-Optimized REST API is deployed globally using Amazon CloudFront as a content delivery network (CDN). This type of API is optimized for latency and performance by caching content at AWS edge locations closer to the user.

Characteristics:

• Global Distribution with CloudFront: Automatically uses CloudFront to route requests to the nearest AWS edge location.
• Low Latency for Global Clients: Provides optimized performance by reducing the round-trip time between the client and the API Gateway.
• Default Caching: Content is cached at edge locations by default, improving performance for frequently accessed data.
• Automatic SSL Management: AWS handles SSL/TLS termination with CloudFront at the edge locations.

Use Cases:

• Global Applications: When you need to serve users worldwide with minimal latency.
• Public APIs: Suitable for public-facing APIs with high distribution needs, such as mobile apps, IoT, and web apps.
• Multi-Region Failover: Edge-optimized APIs automatically route requests to the nearest region with failover capabilities.

3. Private REST API
A Private REST API is accessible only from within your VPC (Virtual Private Cloud), making it ideal for internal or private APIs. Access is restricted to clients in the same VPC, allowing better control and security for sensitive data.

Characteristics:

• VPC Access Only: Only accessible from within the specified VPCs, using VPC endpoint (Interface Endpoint) for access.
• Enhanced Security: Not accessible over the internet, making it ideal for internal applications and services that require limited access.
• No CloudFront Distribution: This API type does not use CloudFront or any public endpoints, as all traffic is restricted to VPC traffic.
• AWS PrivateLink: Uses AWS PrivateLink for secure connections between the VPC and API Gateway.

Use Cases:

• Internal APIs: For services that need to be accessed only by other applications within the VPC.
• Secure, Sensitive Data: Suitable for accessing sensitive internal systems and data that shouldn’t be publicly accessible.
• Microservices in VPC: Ideal for microservices architecture where services communicate within a VPC environment securely.