API Gateway integration types

Giới thiệu

Khi cấu hình một method trong Amazon API Gateway (REST API), bạn phải chọn Integration Type - cách API Gateway kết nối với backend với hai nhóm chính như sau:

• Proxy Integration (AWS_PROXY, HTTP_PROXY, VPC Link + Proxy): API Gateway hoạt động như pass-through - chuyển tiếp nguyên vẹn request đến backend, không transform gì cả.
• Non-Proxy Integration (AWS, HTTP, VPC Link + Non-Proxy): API Gateway đóng vai trò trung gian xử lý - có thể transform request/response bằng Mapping Template (VTL) trước khi gửi đến backend và trả về client.

Mapping Templates

Mapping Template là công cụ để API Gateway transform request/response trước khi gửi đến backend và trả về client, sử dụng ngôn ngữ Velocity Template Language (VTL).

Cụ thể, Mapping Template cho phép bạn:

• Đổi tên / chỉnh sửa query string parameters - ví dụ: đổi ?user_id= thành ?userId= cho phù hợp với backend
• Chỉnh sửa body content - thêm, bớt, hoặc restructure các field trong request/response body
• Thêm headers - thêm header trước khi gửi đến backend
• Filter output - loại bỏ các field không cần thiết trong response trả về client
• Logic điều kiện - VTL hỗ trợ if/else, for loop để xử lý data phức tạp
• Content-Type - có thể set là application/json hoặc application/xml

Các loại Integration Types

1. AWS_PROXY (Lambda Proxy Integration)

• API Gateway chuyển tiếp toàn bộ request đến Lambda function
• Không cần cấu hình mapping template
• Lambda bắt buộc trả response đúng format (statusCode, headers, body, isBase64Encoded.)
• Nếu Lambda trả sai format -> 502 Bad Gateway
• Use case: dùng khi muốn Lambda xử lý toàn bộ logic và không cần transform data ở tầng API Gateway.
• AWS Console setting:

2. AWS (Lambda Custom / AWS Service Integration)

• API Gateway cho phép transform request/response bằng Mapping Template (VTL)
• Có thể tích hợp trực tiếp với AWS services mà không cần Lambda làm trung gian (ví dụ: API Gateway → SQS, API Gateway → DynamoDB, API Gateway → Step Functions)
• Phải cấu hình Integration Request và Integration Response
• Use case: Tích hợp trực tiếp API Gateway với AWS services (SQS, DynamoDB, SNS, Step Functions...) mà không cần Lambda. Hoặc khi cần transform data trước khi gửi đến Lambda.
• AWS Console setting:

3. HTTP_PROXY

• API Gateway chuyển tiếp toàn bộ request đến một HTTP endpoint bên ngoài (ví dụ: ALB, on-premises server, third-party API)
• Không cần cấu hình mapping template
• Hoạt động tương tự AWS_PROXY nhưng backend là HTTP endpoint thay vì Lambda
• Use case: Expose một HTTP backend có sẵn (on-premises, ECS + ALB, third-party API) thông qua API Gateway mà không cần transform data.
• AWS Console setting:

4. HTTP (HTTP Custom Integration)

• API Gateway cho phép transform request/response bằng Mapping Template (VTL) trước khi gửi đến HTTP endpoint
• Phải cấu hình Integration Request và Integration Response
• Hoạt động tương tự AWS nhưng backend là HTTP endpoint thay vì AWS service
• Use case: Khi cần transform request/response trước khi gửi đến HTTP backend. Ví dụ: client gửi request dạng HTTP, Mapping Template chuyển đổi sang json trước khi gửi đến HTTP Endpoint backend.
• AWS Console setting:

5. VPC Link

Mặc định, API Gateway chỉ có thể kết nối đến các backend publicly accessible (có public IP hoặc public DNS). Nếu backend nằm trong private VPC (ví dụ: ECS trên private subnet, on-premises qua Direct Connect/VPN), API Gateway không thể truy cập trực tiếp.

VPC Link giải quyết vấn đề này bằng cách tạo một kết nối private từ API Gateway vào trong VPC mà không cần expose backend ra internet.

• VPC Link kết nối API Gateway với NLB hoặc ALB nằm trong VPC để forward traffic đến các private resource phía sau (ECS, EC2, on-premises...)
• Toàn bộ traffic đi qua AWS private network, không qua internet
• VPC Link cũng có Option Use Proxy Integration:
  • Proxy: pass-through, không cần mapping template, backend tự xử lý response format
  • Non-Proxy: hỗ trợ Mapping Template (VTL) để transform request/response
• Use case: Backend nằm trong private subnet (ECS, EC2), on-premises server qua Direct Connect hoặc VPN, cần bảo mật không expose backend ra internet.
• AWS Console setting:

6. MOCK

• API Gateway tự trả về response mà không cần gọi đến bất kỳ backend nào
• Phải cấu hình Integration Request và Integration Response để định nghĩa response trả về
• Không có network call ra ngoài, API Gateway xử lý hoàn toàn
• Use case: Mock API trong giai đoạn phát triển khi backend chưa sẵn sàng, hoặc trả response cố định cho các endpoint như health check, CORS preflight.
• AWS Console setting:

Tóm tắt API integration type

Tổng kết

Qua bài viết này, chúng ta đã cùng tìm hiểu toàn bộ Integration Type của API Gateway — từ cách hoạt động, Mapping Template đến use case thực tế. Hy vọng bạn đã có cái nhìn rõ ràng và hệ thống hơn về chủ đề này. Gặp scenario trong đề thi hoặc trong dự án thực tế, hãy đi theo flow sau:

1. Backend là Lambda hay AWS Service? 
   • Lambda không cần transform → AWS_PROXY
   • Lambda cần transform/AWS Services → AWS
2. Backend là HTTP endpoint bên ngoài? 
   • Không cần transform → HTTP_PROXY 
   • Cần transform (legacy API, đổi format...) → HTTP
3. Backend nằm trong private VPC
   • Không cần transform → VPC Link PROXY
   • Cần transform → VPC Link NON_PROXY
4. Không cần backend thật (đang dev/test) → MOCK

Chúc các bạn ôn tập tốt và ứng dụng thành công vào dự án thực tế nhé!

Tài liệu tham khảo

• Integrations for REST APIs in API Gateway
• Choose an API Gateway API integration type
• Private integrations for REST APIs in API Gateway
• Build scalable REST APIs using Amazon API Gateway private integration with Application Load Balancer
• Mapping template transformations for REST APIs in API Gateway