API Composition là gì? 7 kỹ thuật tổng hợp API

Trả lời nhanh: API Composition là gì? Đây là kỹ thuật gọi nhiều API hoặc service, sau đó hợp nhất dữ liệu thành một response phục vụ đúng màn hình hay nghiệp vụ. Có thể tổng hợp ở client, aggregator service, API gateway, Backend for Frontend, GraphQL, edge hoặc read model. Lựa chọn đúng phụ thuộc latency, cache, độ ổn định và ownership.

Cập nhật lần cuối: 20/08/2026

Một màn hình đơn hàng tưởng như đơn giản có thể cần dữ liệu từ bốn nơi:

hồ sơ khách hàng;
danh sách đơn gần nhất;
trạng thái vận chuyển;
sản phẩm đề xuất.

Nếu dữ liệu nằm trong bốn service độc lập, không service nào trả về trọn vẹn màn hình. Một thành phần phải gọi các API, kết hợp kết quả, đổi tên trường và xử lý trường hợp một dependency không phản hồi.

Đó là API Composition.

Viết đoạn code ghép JSON khá dễ. Phần khó là quyết định đoạn code đó chạy ở đâu, có được phép giữ cache không, timeout bao lâu, lỗi một service có làm hỏng toàn trang không và team nào chịu trách nhiệm khi contract thay đổi.

API Composition là gì?

API Composition là mẫu kiến trúc trong đó một thành phần truy vấn nhiều API hoặc microservice và thực hiện phép join ở tầng ứng dụng để tạo response tổng hợp. Nó thường xuất hiện khi hệ thống dùng database-per-service hoặc khi một trải nghiệm người dùng cần dữ liệu từ nhiều domain.

Ví dụ một endpoint tổng hợp có thể nhận:

GET /customer-dashboard/123

Sau đó gọi song song:

GET /customers/123
GET /orders?customer_id=123&limit=5
GET /shipments?order_ids=...
GET /recommendations?customer_id=123

Cuối cùng, nó trả về một object được thiết kế theo nhu cầu của màn hình, không theo cấu trúc nội bộ của từng service.

API Composition khác aggregation và orchestration thế nào?

Ba thuật ngữ thường bị dùng lẫn nhau:

Khái niệm	Trọng tâm	Ví dụ
Composition	Kết hợp dữ liệu hoặc năng lực từ nhiều API	Ghép profile, order và shipment
Aggregation	Thu thập nhiều response thành một response	Gateway fan-out rồi merge JSON
Orchestration	Điều phối chuỗi bước có thứ tự và trạng thái	Tạo đơn, giữ tồn kho, thanh toán, gửi mail

Aggregation thường là một kỹ thuật cụ thể bên trong API Composition. Orchestration rộng hơn vì có thể bao gồm command, retry nghiệp vụ, compensation và workflow kéo dài.

Một quy tắc hữu ích:

nếu mục tiêu chính là đọc và ghép dữ liệu, nghĩ tới composition;
nếu mục tiêu là thực hiện nhiều thay đổi có thứ tự, nghĩ tới orchestration hoặc saga;
không biến một endpoint đọc dữ liệu thành workflow ghi phức tạp chỉ vì cùng gọi nhiều service.

Vì sao gọi API trực tiếp từ client thường chậm?

Nếu mobile app gọi bốn service qua mạng di động, nó chịu bốn kết nối, bốn lần TLS và bốn round trip xa. Nếu đặt một aggregator gần backend, client chỉ thực hiện một round trip xa. Aggregator gọi bốn service qua mạng nội bộ và có thể chạy song song.

Microsoft mô tả Gateway Aggregation là cách giảm độ “chatty” giữa client và backend. Lợi ích thường rõ nhất với mobile, thiết bị yếu hoặc mạng có latency cao.

Tuy vậy, thêm aggregator không tự động nhanh hơn. Nó còn tạo:

một network hop;
điểm nghẽn mới;
dependency fan-out;
yêu cầu scale và observability;
nguy cơ cascading failure.

Hiệu năng cuối cùng phụ thuộc vị trí, cách gọi song song, caching, payload và timeout.

Over-fetching và under-fetching là gì?

Over-fetching

Client nhận nhiều trường hơn nhu cầu. Ví dụ màn hình chỉ cần name và avatar, nhưng API profile trả cả lịch sử, permission và metadata.

Hậu quả là tăng bandwidth, thời gian serialize và rủi ro làm lộ dữ liệu không cần thiết.

Under-fetching

Một response không đủ để render trải nghiệm, khiến client phải gọi thêm nhiều endpoint. Hậu quả là tăng round trip, code điều phối ở client và trạng thái loading phức tạp.

API Composition cố gắng tạo response vừa đủ cho use case. GraphQL giải bài toán bằng việc cho client chọn field, còn BFF hoặc aggregator thiết kế endpoint theo từng experience.

Bảy kỹ thuật tổng hợp API phổ biến

1. Client-side composition

Web hoặc mobile app trực tiếp gọi nhiều API rồi merge dữ liệu.

Phù hợp khi:

chỉ có ít dependency;
service đã public và cùng cơ chế auth;
latency giữa client và service thấp;
mỗi client cần dữ liệu rất khác nhau;
team muốn thử nghiệm nhanh.

Rủi ro:

lộ topology nội bộ;
nhiều round trip xa;
logic lỗi và retry bị lặp giữa iOS, Android, web;
khó rollout thay đổi contract đồng thời;
client cũ có thể tồn tại nhiều tháng.

Client-side composition đơn giản lúc đầu nhưng dễ biến mỗi ứng dụng thành một orchestrator phân tán.

2. Aggregator service

Một service chuyên nhận request, fan-out tới dependency và merge kết quả.

Phù hợp khi:

có một use case tổng hợp ổn định;
cần logic join hoặc transformation đáng kể;
muốn ownership rõ theo domain hoặc journey;
cần cache và observability riêng.

Aggregator nên chứa logic composition, không sao chép business rule của service nguồn. Nếu nó bắt đầu quyết định tồn kho, quyền hay giá, ranh giới domain đang bị xói mòn.

3. API Gateway Aggregation

API gateway thực hiện routing, auth, rate limit và có thể gọi nhiều backend để hợp nhất response.

Phù hợp khi:

logic merge nhẹ;
cần một public endpoint;
cross-cutting concern đã tập trung ở gateway;
số pattern tổng hợp không quá lớn.

Không phù hợp khi:

transformation chứa nhiều business logic;
release composition cần độc lập với gateway;
nhiều team cùng đưa logic khó kiểm soát vào một điểm trung tâm.

Gateway quá “thông minh” có thể trở thành monolith mới và single point of failure.

4. Backend for Frontend (BFF)

BFF tạo backend riêng cho từng loại client hoặc experience, ví dụ mobile BFF, web BFF và partner BFF.

Microsoft nhấn mạnh mobile và desktop có thể cần pagination, cache và payload khác nhau. BFF cho phép mỗi frontend tối ưu mà không buộc tất cả dùng một contract chung quá rộng.

Lợi ích:

ownership gần team frontend;
payload đúng theo experience;
release độc lập;
giảm điều kiện if mobile else web trong gateway chung.

Chi phí:

tăng số service vận hành;
có thể lặp code auth, mapping và client SDK;
cần guardrail để BFF không trở thành nơi sao chép domain logic.

5. GraphQL composition

GraphQL cung cấp schema có kiểu, cho phép client yêu cầu đúng field cần thiết. Resolver có thể lấy dữ liệu từ nhiều service. Với hệ thống lớn, federation chia schema thành subgraph theo team rồi compose thành supergraph.

GraphQL Foundation mô tả Federation như cách chia việc xây schema theo ranh giới team. Lợi ích không chỉ là query linh hoạt, mà còn là hợp tác và governance quanh một schema chung.

Phù hợp khi:

nhiều client cần nhiều lát cắt dữ liệu;
quan hệ giữa entity quan trọng;
team chấp nhận đầu tư schema, resolver và query planning;
có cơ chế schema check và observability.

Rủi ro:

N+1 query;
query quá đắt;
cache HTTP phức tạp hơn;
field ownership không rõ;
breaking change ở subgraph gây lỗi composition.

Apollo khuyến nghị dùng schema check trong CI để xác nhận subgraph mới compose được và không phá operation đang hoạt động.

6. Edge composition

Logic tổng hợp chạy ở CDN edge hoặc worker gần người dùng. Edge có thể lấy fragment từ nhiều origin, áp dụng personalization nhẹ và ghép response.

Phù hợp khi:

latency tới người dùng quan trọng;
phần dữ liệu cache được ở edge;
logic nhẹ và giới hạn runtime rõ;
backend ở nhiều region.

Rủi ro:

runtime, memory và thời gian chạy bị giới hạn;
secret và quyền truy cập cần quản lý chặt;
tracing xuyên edge và origin khó hơn;
không nên đặt transaction dài ở edge.

7. Read model hoặc materialized view

Thay vì gọi nhiều service ở request time, hệ thống đồng bộ event vào một read model được thiết kế cho query. Client đọc từ một nơi.

Phù hợp khi:

cùng một join được thực hiện rất thường xuyên;
dependency fan-out tạo latency hoặc availability kém;
chấp nhận eventual consistency;
cần query và filter phức tạp.

Chi phí:

vận hành pipeline event;
xử lý replay, duplicate và schema evolution;
dữ liệu có độ trễ;
cần cơ chế đối soát với source of truth.

Read model chuyển độ phức tạp từ request time sang data synchronization. Nó không loại bỏ độ phức tạp, chỉ đặt nó ở nơi kiểm soát tốt hơn cho một số workload.

Nên chọn kỹ thuật nào?

Tình huống	Lựa chọn đầu tiên để đánh giá
Prototype, 2 API, web nhanh	Client-side composition
Một màn hình quan trọng, logic join rõ	Aggregator service
Merge nhẹ tại public entry point	Gateway aggregation
Mobile và web có nhu cầu khác biệt lớn	BFF
Nhiều client, schema quan hệ, field linh hoạt	GraphQL
Nội dung cache được, cần latency toàn cầu	Edge composition
Join lặp lại, fan-out lớn, chấp nhận trễ dữ liệu	Read model

Không cần chọn một pattern cho toàn hệ thống. Một kiến trúc có thể dùng gateway ở biên, BFF theo client, GraphQL cho query và read model cho dashboard nặng.

Partial failure nên được xử lý thế nào?

Khi một response phụ thuộc bốn service, availability tổng thể có thể giảm. Nếu mọi service đều bắt buộc, chỉ một lỗi cũng làm cả request lỗi.

Trước khi viết code, hãy phân loại field:

required: thiếu thì không thể hoàn thành trải nghiệm;
optional: có thể ẩn section;
stale-acceptable: có thể dùng cache cũ;
deferred: tải sau hoặc stream sau.

Ví dụ trang đơn hàng có thể coi profile và order là required, recommendation là optional, còn trạng thái vận chuyển có thể dùng cache cũ kèm nhãn thời gian.

Response có thể trả metadata rõ:

{
  "profile": { "id": "123", "name": "Long" },
  "orders": [/* ... */],
  "recommendations": [],
  "warnings": [
    { "source": "recommendation", "code": "TEMPORARILY_UNAVAILABLE" }
  ]
}

Không nên trả dữ liệu thiếu mà im lặng, vì client và người dùng sẽ hiểu nhầm trạng thái.

Timeout, retry và circuit breaker nên đặt ra sao?

Timeout

Aggregator cần một deadline tổng. Mỗi dependency nhận một phần ngân sách, không phải toàn bộ. Nếu request budget là 800 ms, không thể cho ba service lần lượt chờ 800 ms.

Retry

Retry chỉ phù hợp với lỗi tạm thời và operation an toàn. Retry đồng loạt có thể tạo retry storm khi backend đang quá tải. Dùng backoff, jitter và giới hạn số lần.

Circuit breaker

Khi một dependency lỗi liên tục, circuit breaker dừng gọi tạm thời, trả fallback nhanh và cho hệ thống thời gian phục hồi.

Bulkhead

Tách pool tài nguyên theo dependency hoặc loại request để một service chậm không chiếm hết connection, thread hay worker.

Microsoft khuyến nghị load test gateway và dùng bulkhead, circuit breaking, retry, timeout để tránh cascading failure.

Cache API tổng hợp khó ở điểm nào?

Một response có thể chứa dữ liệu với TTL khác nhau:

profile đổi ít;
order đổi vừa;
shipment đổi nhanh;
recommendation có thể tính lại theo phiên.

Cache cả response theo TTL ngắn nhất làm giảm hit rate. Cache theo TTL dài nhất làm dữ liệu nhanh bị cũ.

Có bốn chiến lược:

Cache từng dependency: linh hoạt nhưng tăng số lớp.
Cache response tổng: đơn giản, phù hợp khi dữ liệu có nhịp thay đổi gần nhau.
Stale-while-revalidate: trả cache cũ trong khi cập nhật nền.
Materialized view: dựng sẵn response hoặc read model từ event.

Cache key phải xét user, permission, locale, query và version. Tuyệt đối không để dữ liệu cá nhân hóa của người này được phục vụ cho người khác.

Auth và phân quyền nên chạy ở đâu?

Gateway có thể xác thực token, nhưng service nguồn vẫn phải kiểm tra quyền phù hợp với domain. Aggregator không nên dùng một service account quyền rộng rồi vô tình vượt quyền của người dùng.

Một nguyên tắc an toàn:

xác thực danh tính ở biên;
truyền context quyền tối thiểu;
service nguồn thực thi authorization;
lọc field trước khi merge;
không log token và dữ liệu nhạy cảm;
audit ai đã truy cập dữ liệu nào.

Nếu API được gọi bởi AI Agent, tool schema và permission càng cần thu hẹp. Bài rủi ro AI Agent trong Marketing cung cấp checklist cho quyền đọc, ghi và phê duyệt.

Ownership của composition layer thuộc về ai?

Một composition layer nằm giữa nhiều domain nên dễ rơi vào vùng “không ai sở hữu”. Có ba mô hình:

Platform team sở hữu gateway chung

Phù hợp với auth, rate limit, routing và policy. Không nên để platform team trở thành bottleneck cho mọi thay đổi experience.

Product team sở hữu BFF hoặc aggregator

Phù hợp khi logic gắn chặt với journey. Team có thể release cùng frontend và chịu KPI trải nghiệm.

Domain team sở hữu subgraph

Phù hợp với GraphQL federation. Mỗi team quản field thuộc domain, còn schema governance và router là năng lực chung.

Quy tắc thực tế: team chịu trách nhiệm về outcome của experience nên sở hữu composition gần experience, còn domain rule vẫn ở service nguồn.

Cách triển khai API Composition an toàn

Bước 1: Vẽ dependency graph

Liệt kê service, call tuần tự, call song song, dữ liệu required và optional.

Bước 2: Đặt latency budget

Xác định SLA tổng, ngân sách cho từng dependency và fallback khi quá hạn.

Bước 3: Chọn vị trí composition

Dựa trên network, ownership, cache, client diversity và mức business logic.

Bước 4: Định nghĩa contract tổng hợp

Dùng schema rõ, error model nhất quán và field-level policy. Không rò cấu trúc nội bộ không cần thiết.

Bước 5: Xử lý partial failure

Gắn nhãn required, optional, stale-acceptable và deferred. Viết test cho từng dependency bị lỗi.

Bước 6: Thêm resilience

Timeout, retry có giới hạn, circuit breaker, bulkhead, rate limit và cache fallback.

Bước 7: Quan sát toàn đường đi

Truyền correlation ID, distributed trace và metric theo dependency. Log latency, error, cache hit và payload size.

Bước 8: Load test và chaos test

Thử backend chậm, trả dữ liệu sai schema, connection reset và traffic tăng. Quan sát cascading failure.

Bước 9: Quản lý version

Kiểm tra backward compatibility, consumer-driven contract hoặc schema check trong CI.

Metric nào cần theo dõi?

end-to-end latency P50, P95, P99;
latency và error rate theo dependency;
fan-out call count trên mỗi request;
tỷ lệ partial response;
timeout và circuit breaker open rate;
cache hit theo lớp;
payload size trước và sau composition;
số request bị retry;
saturation của connection pool và worker;
breaking change bị chặn trước deploy.

Không nên chỉ theo dõi status code của aggregator. Một response 200 có thể thiếu dữ liệu quan trọng hoặc chứa fallback cũ.

FAQ - Câu hỏi thường gặp

API Composition có phải API Gateway không?

Không. API Composition là bài toán và mẫu ghép dữ liệu từ nhiều API. API Gateway là một vị trí có thể thực hiện composition, bên cạnh client, BFF, GraphQL, edge hoặc aggregator riêng.

API Composition có làm tăng latency không?

Nó thêm một hop nếu chạy server-side, nhưng thường giảm tổng latency khi thay nhiều round trip xa bằng một round trip xa và nhiều call nội bộ chạy song song. Cần benchmark vì fan-out, serialization và dependency chậm có thể làm kết quả xấu hơn.

GraphQL có thay thế mọi aggregator không?

Không. GraphQL phù hợp với schema quan hệ và nhiều client cần field linh hoạt. Aggregator REST hoặc BFF có thể đơn giản hơn cho một use case cố định. GraphQL vẫn cần resolver, batching, cache, auth và xử lý dependency lỗi.

API Composition có dùng cho thao tác ghi không?

Có thể, nhưng thao tác ghi nhiều service thường cần orchestration, saga, idempotency và compensation. Không nên chỉ fan-out command rồi coi request thành công khi trạng thái chưa nhất quán.

Pattern nào phù hợp cho AI Agent gọi nhiều API?

Bắt đầu bằng gateway hoặc tool layer có schema hẹp, quyền tối thiểu và validation. Với read-heavy workflow, aggregator có thể giảm số tool call. Hành động ghi hoặc chi tiền cần phê duyệt, idempotency và audit.

Tóm lại

API Composition là cách gọi nhiều service và ghép kết quả cho một use case.
Vị trí composition quyết định latency, cache, versioning, resilience và ownership.
Bảy lựa chọn phổ biến là client, aggregator, gateway, BFF, GraphQL, edge và read model.
Dependency phải được phân loại required, optional, stale-acceptable hoặc deferred.
Timeout, retry, circuit breaker và bulkhead cần được thiết kế theo deadline tổng.
GraphQL giải over-fetching và schema composition nhưng tạo bài toán query cost và governance.
Kiến trúc tốt giữ business rule ở domain service, còn composition gần team chịu trách nhiệm trải nghiệm.

API Composition là gì?

API Composition khác aggregation và orchestration thế nào?

Vì sao gọi API trực tiếp từ client thường chậm?

Over-fetching và under-fetching là gì?

Over-fetching

Under-fetching

Bảy kỹ thuật tổng hợp API phổ biến

1. Client-side composition

2. Aggregator service

3. API Gateway Aggregation

4. Backend for Frontend (BFF)

5. GraphQL composition

6. Edge composition

7. Read model hoặc materialized view

Nên chọn kỹ thuật nào?

Partial failure nên được xử lý thế nào?

Timeout, retry và circuit breaker nên đặt ra sao?

Timeout

Retry

Circuit breaker

Bulkhead

Cache API tổng hợp khó ở điểm nào?

Auth và phân quyền nên chạy ở đâu?

Ownership của composition layer thuộc về ai?

Platform team sở hữu gateway chung

Product team sở hữu BFF hoặc aggregator

Domain team sở hữu subgraph

Cách triển khai API Composition an toàn

Bước 1: Vẽ dependency graph

Bước 2: Đặt latency budget

Bước 3: Chọn vị trí composition

Bước 4: Định nghĩa contract tổng hợp

Bước 5: Xử lý partial failure

Bước 6: Thêm resilience

Bước 7: Quan sát toàn đường đi

Bước 8: Load test và chaos test

Bước 9: Quản lý version

Metric nào cần theo dõi?

FAQ - Câu hỏi thường gặp

API Composition có phải API Gateway không?

API Composition có làm tăng latency không?

GraphQL có thay thế mọi aggregator không?

API Composition có dùng cho thao tác ghi không?

Pattern nào phù hợp cho AI Agent gọi nhiều API?

Tóm lại

Nguồn tham khảo

Đọc tiếp