AWS API Gateway: A Practical, Step-by-Step Guide

🔗 What Is API Gateway?

AWS API Gateway is the entry point for your backend APIs. It securely connects your frontend apps (web/mobile) to AWS Lambda, EC2, ECS, or on-premise systems. Think of it as a "front door" that controls who can enter, how fast, and where they go.

API Types

Type	Description	Best For
HTTP API	Modern, cheaper, faster	CRUD / serverless APIs
REST API	Full-featured (usage plans, caching)	Complex, enterprise APIs
WebSocket API	Real-time, 2-way communication	Chat apps, live dashboards

🔧 Step 1: Create Your First API (Console)

1. Go to API Gateway → Create API → HTTP API.
2. Choose Build.
3. Add an Integration (e.g., AWS Lambda or HTTP backend).

4. Create routes like:

5. GET /notes

6. POST /notes
7. Create a Deployment and Stage (e.g., dev).
8. Copy your Invoke URL and test in Postman.

Example: https://abc123.execute-api.us-east-1.amazonaws.com/notes

📦 Step 2: Routes and Integrations

A route defines what happens when someone calls /notes.

Example:

• Route: GET /notes
• Integration: Lambda function notes_get

Console Steps:

1. Go to Routes → Create.
2. Enter /notes and choose method GET.
3. Choose Integration: Lambda → notes_get.
4. Deploy to stage dev.

🚶 Step 3: Stages & Variables

Stages represent environments like dev, test, prod.

Example:

• Stage: dev (testing)
• Stage: prod (live users)

You can add Stage Variables, e.g.:

• ENV = dev
• DB_URL = mydb-dev.example.com

⏱️ Step 4: Throttling (Rate & Burst)

Control request limits to protect your backend.

Example:

• Rate = 100 req/sec
• Burst = 200 req/sec

Console Steps:

1. Stages → dev → Throttling.
2. Set Rate and Burst limits.
3. Save.

If clients exceed limits, API Gateway returns 429 Too Many Requests.

🌐 Step 5: Enable CORS

Without CORS, browsers will block frontend requests from different domains.

Example: Your frontend at https://imjoy.me calls your API at https://api.imjoy.me.

Console Steps:

1. In API Gateway, go to CORS settings.
2. Allowed origins: https://imjoy.me
3. Allowed methods: GET, POST, DELETE
4. Allowed headers: Content-Type, Authorization
5. Save and redeploy.

📘 Diagram: CORS Flow

+------------+        +------------------+        +-------------------+
|  Browser   | -----> |  API Gateway     | -----> |  Lambda Backend   |
| (Frontend) | <----- | (CORS Response)  | <----- | (Business Logic)  |
+------------+        +------------------+        +-------------------+

When the browser sends a preflight OPTIONS request, API Gateway replies with headers like:

Access-Control-Allow-Origin: https://imjoy.me
Access-Control-Allow-Methods: GET,POST,DELETE
Access-Control-Allow-Headers: Content-Type,Authorization

🔐 Step 6: Authorization

Secure your API using AWS Cognito or Lambda authorizers.

Options:

• NONE = public
• IAM = internal AWS calls
• COGNITO_USER_POOLS = validate JWT tokens
• LAMBDA = custom logic (Auth0, DB checks)

Console Steps:

1. Authorizers → Create.
2. Choose Cognito User Pool.
3. Token source: Authorization header.
4. Attach to route (e.g., GET /notes).
5. Redeploy.

Example JWT Header

Authorization: Bearer eyJraWQiOiJ...<token>...

📘 Diagram: Auth Flow

+-----------+       +---------------+       +-------------+       +-------------+
|  User     | --->  | Cognito Login | --->  | API Gateway | --->  | Lambda      |
| (Frontend)|       |  (JWT Token)  |       |  Authorizer |       |  Backend    |
+-----------+       +---------------+       +-------------+       +-------------+

1. User logs in with Cognito and gets a JWT.
2. Frontend sends request with JWT in Authorization header.
3. API Gateway validates token before invoking Lambda.

🔥 Step 7: Custom Domain

Change default AWS URL to a friendly one.

Console Steps:

1. Custom Domain Names → Create.
2. Enter: api.imjoy.me.
3. Select TLS certificate from ACM.
4. Add API mapping to your stage.
5. Update DNS (Route 53) with an alias record to API Gateway domain.

Result: https://api.imjoy.me/notes

🛠 Step 8: VPC Link (Private Backend)

Connect API Gateway to private resources in a VPC (e.g., ALB, ECS, or EC2).

Console Steps:

1. VPC Links → Create.
2. Select subnets in your private VPC.
3. Integration → Create: choose Private Resource via VPC Link.
4. Attach to route (e.g., /internal).
5. Redeploy.

📘 Diagram: VPC Link

+------------+      +----------------+      +-------------------+
|  Internet  | ---> | API Gateway    | ---> |  ALB (Private)    |
|  Clients   |      | (VPC Link)     |      |  ECS / EC2 App    |
+------------+      +----------------+      +-------------------+

🔄 Step 9: Export & Reimport APIs

Export (Console):

1. Stages → dev → Export.
2. Choose format: OpenAPI 3.
3. Download JSON/YAML.

Reimport:

1. Create API → Import from OpenAPI.
2. Upload file.
3. Review and create.

📊 Step 10: Monitor Metrics & Logs

• Enable Logs: Stages → dev → Logging → Enable access logs.
• View in CloudWatch: Latency, 4XX/5XX errors.
• Enable X-Ray: Trace end-to-end requests.

📅 Pricing Snapshot

API Type	Cost per 1M req	Free Tier
HTTP API	~$1.00	1M / month
REST API	~$3.50	1M / month
WebSocket	~$1.00	1M messages

Data Transfer: ~$0.09/GB to internet.

Pro Tip: Create AWS Budgets to avoid surprise bills.

🎯 Summary Table

Feature	Purpose	Example	Console Path
Routes	Define endpoints	GET /notes	API → Routes
Integrations	Connect backend	Lambda/HTTP	API → Integrations
CORS	Allow frontend calls	https://imjoy.me	API → CORS
Auth	Secure access	Cognito, JWT	API → Authorizers
Stages	Versioning	dev, prod	API → Deployments
VPC Link	Private access	ALB/ECS	API → VPC Links
Export/Reimport	API migration	OpenAPI spec	API → Stages → Export

🔍 Final Thoughts

AWS API Gateway may look overwhelming at first, but once you break it down into Routes, Integrations, Stages, CORS, and Auth, it becomes a powerful, low-cost serverless gateway for your apps.