The best API composition patterns for microservices depend on your goals: reduce chatty calls, hide service complexity, improve performance, and keep clients simple. The most common and effective patterns are:

1. API Gateway

A single entry point for clients that routes requests to multiple backend services.

Best for:

• Centralizing authentication, rate limiting, logging, and routing
• Simplifying client access
• Mobile/web backends

Pros:

• Reduces client complexity
• Good place for cross-cutting concerns

Cons:

• Can become a bottleneck or monolith if overloaded
• Risk of putting too much business logic in the gateway

---

2. Backend for Frontend (BFF)

A specialized API layer per client type, such as one for web and one for mobile.

Best for:

• Different client needs and payload shapes
• Optimizing for UI-specific data requirements

Pros:

• Tailored responses per client
• Avoids overfetching/underfetching
• Keeps client logic thin

Cons:

• More services to maintain
• Risk of duplicated logic across BFFs

---

3. Aggregator / Composite Service

A service that calls multiple microservices and combines their responses into one.

Best for:

• Read-heavy workflows
• Building a single view from multiple domains
• Reducing multiple client round-trips

Pros:

• Client gets a unified response
• Encapsulates composition logic server-side

Cons:

• Extra latency if calls are sequential
• Must handle partial failures carefully

---

4. CQRS with Read Models

Instead of composing data on demand, maintain a prebuilt read model optimized for queries.

Best for:

• High-scale read scenarios
• Complex joins across services
• Performance-sensitive endpoints

Pros:

• Fast reads
• Avoids runtime fan-out to many services

Cons:

• Eventual consistency
• More infrastructure and data synchronization complexity

---

5. Event-Driven Composition

Services publish events, and a consumer builds a materialized view or projection.

Best for:

• Decoupled systems
• Async workflows
• Strong scalability and resilience needs

Pros:

• Loose coupling
• Good for asynchronous aggregation

Cons:

• Not suitable for strict real-time consistency
• Debugging and replay complexity

---

6. GraphQL as a Composition Layer

A GraphQL API can fetch data from multiple services and present a unified schema.

Best for:

• Flexible client queries
• Complex data fetching needs
• Frontend-driven composition

Pros:

• Clients request exactly what they need
• Strong schema and type system

Cons:

• Resolver performance can be tricky
• Requires careful batching/caching to avoid N+1 problems

---

7. Service Mesh + Sidecar-based Composition

Less about API shaping, more about enabling service-to-service communication, retries, mTLS, routing, and observability.

Best for:

• Large service ecosystems
• Platform-level control and reliability

Pros:

• Improves resilience and traffic management
• Transparent to application code in many cases

Cons:

• Doesn’t replace API composition logic itself
• Operational complexity

---

Practical guidance

Use this rule of thumb:

• Simple client needs + many backend services → API Gateway
• Different client types → BFF
• Need to combine multiple service responses synchronously → Aggregator/Composite Service
• High-performance queries across many domains → CQRS / Read Models
• Want eventual consistency and loose coupling → Event-driven projections
• Flexible client-side data needs → GraphQL

---

Common best practices

• Keep composition logic out of core domain services
• Prefer parallel calls over sequential ones where possible
• Add timeouts, retries, circuit breakers, and fallbacks
• Avoid deep fan-out chains
• Cache frequently requested aggregated data
• Use schema contracts and versioning carefully
• Monitor latency, error rates, and downstream dependencies

---

What to avoid

• Making the API gateway a “god service”
• Synchronous composition across too many services in one request
• Tight coupling between services through shared database joins
• Hidden N+1 calls in GraphQL or orchestration layers

---

If you want, I can also give you:

1. a decision matrix for choosing the right pattern, or
2. example architectures for a typical e-commerce or SaaS platform.