An API composite list aggregates data from multiple sources into a single, unified response that combines different data types or attributes. Developers use composite lists to fetch related resources in one request, reduce round-trips to backend systems, and create cohesive data structures that serve frontend applications and integrations without requiring multiple sequential API calls.
A composite list is an API response that bundles data from multiple sources, endpoints, or resource types into a single payload. Rather than making separate calls to fetch users, their orders, and their payment methods individually, a composite endpoint returns all related data together in one structured response.
This pattern is common in GraphQL APIs (where it's fundamental to the query language), REST APIs with expansion parameters, and gateway services that coordinate multiple backend systems. Composite lists reduce network overhead, simplify client-side logic, and improve perceived application performance by eliminating the "N+1 query" problem.
Expansion Parameters: REST APIs often use query parameters like ?expand=related_resources to include nested data. A single endpoint returns a user object with their embedded address, billing info, and recent orders.
GraphQL Queries: GraphQL is purpose-built for composite data fetching. A single query can request a user's name, email, order history with product details, and payment methods—all optimized to fetch exactly what the client needs.
Batch Endpoints: Some APIs accept multiple resource IDs in a single request and return composite results. For example, POST /batch with {"ids": [1, 2, 3]} returns an array of fully-hydrated objects.
API Gateway Composition: Backend-for-frontend (BFF) layers and API gateways aggregate multiple microservice calls and return a unified response to the client.
Composing data from multiple sources introduces complexity around performance, error handling, and consistency. When your composite endpoint relies on three backend services, what happens if one times out or returns an error?
Parallel Fetching: Fetch from multiple sources concurrently rather than sequentially. Promise.all() in JavaScript, goroutines in Go, or asyncio in Python can dramatically reduce response latency.
Partial Failures: Decide whether a single failed dependency should fail the entire response or return partial data with an error flag. Some applications prefer receiving 90% of the data over none at all.
Caching Strategy: Composite endpoints are expensive to compute. Implement caching at multiple layers: cache individual resource fetches, cache the composite response, and use cache invalidation strategies that refresh when underlying data changes.
Timeout Handling: Set aggressive timeouts on individual fetches within the composite operation, and a hard limit on the overall response time. Return what's available rather than making the client wait indefinitely.
Several categories of tools help implement composite list patterns:
GraphQL Servers: Apollo Server, Hasura, and PostGraphQL automatically generate composite query capabilities from your schema, handling data fetching and optimization.
API Gateways: Kong, AWS API Gateway, and MuleSoft compose requests across multiple backend services, providing request transformation, response aggregation, and lifecycle management.
Backend-for-Frontend (BFF) Frameworks: Next.js API routes, Express middleware layers, and specialized BFF platforms let you compose data tailored to your frontend's exact needs.
Data Integration Platforms: Tools like Zapier, Airbyte, and Fivetran help move and composite data across systems, useful for building composite views of organizational data.
MCP Tools: Modern integration platforms provide access to large catalogs of pre-built connectors across categories, enabling rapid composition of data from hundreds of providers without building custom integrations.
Design for Flexibility: Use query parameters or request bodies to let clients specify which fields and related resources they need. This reduces payload size and unnecessary computation.
Document Expansion Options: Clearly document which resources can be expanded, what fields are included in each expansion, and performance implications of requesting certain combinations.
Version Your Composite Schema: Composite responses combine multiple resources; versioning becomes critical when individual resources change structure. Track version separately from underlying API versions.
Implement Consistent Error Handling: Return structured error responses that indicate which component failed and why. Include partial success indicators when relevant.
Monitor Dependency Health: Track latency and error rates of all upstream dependencies. Composite endpoints amplify the impact of slow or failing services.
Use Request Deduplication: If multiple resources need the same data, fetch once and reuse. Implement request-scoped caching to avoid duplicate calls within a single composite operation.
GraphQL Advantages: Clients request exactly what they need, eliminating over-fetching and under-fetching. Composition is declarative and powerful. Query complexity analysis prevents abuse.
GraphQL Tradeoffs: Requires a query parser and resolver engine. Caching is more complex. Harder to debug than REST. Learning curve for teams unfamiliar with the paradigm.
REST Advantages: Simpler mental model. Easier to cache at HTTP level. Browser-friendly. Familiar to most developers.
REST Tradeoffs: Composition requires designing many endpoints or using expansion parameters. Clients often over-fetch data or make N+1 calls. Less efficient for complex data relationships.
Many teams adopt hybrid approaches: REST for simple resources, GraphQL for composite queries, or REST with aggressive expansion parameters.
| Tool | Provider | Price/call | Cache-hit |
|---|---|---|---|
| Usage Time Series | account | $0 | $0 |
| Per-Tool Usage Breakdown | account | $0 | $0 |
| Usage Summary | account | $0 | $0 |
| Discover Tools | apibase | $0 | $0 |
| Batch Tool Calls | platform | $0 | $0 |
| Tool Quality Metrics | platform | $0 | $0 |
| Tool Quality Rankings | platform | $0 | $0 |
| List Programming Languages | judge0 | $0.001 | $0.0001 |
| Check CVE ID Reservation Status | cve-mitre | $0.001 | $0.0001 |
| Security Advisories (deps.dev) | depsdev | $0.001 | $0.0001 |
| Dependency Tree (deps.dev) | depsdev | $0.001 | $0.0001 |
| Package Info (deps.dev) | depsdev | $0.001 | $0.0001 |
Aggregation typically means combining values (sum, average, count) into a summary. Composition means combining different resource types or related objects into a single structured response. A composite endpoint returns full objects; an aggregate endpoint returns computed summaries.
Fetch all needed IDs first, then batch-fetch all related objects in a single query. Use database joins or batch endpoints. Implement request-scoped caching so repeated lookups within one composite operation don't hit the database twice. GraphQL resolvers use techniques like DataLoader to automatically batch queries.
It depends on your use case. For user checkout flows, you might fail if payment info isn't available. For dashboards, returning partial data with error indicators is often better. Document this behavior clearly and consider providing a fallback mode.
Cache at multiple levels: cache individual resource fetches, cache the composite response as a whole, and use granular invalidation that refreshes only affected components when data changes. Be careful with time-based expiry for composite data that combines fast-changing and stable components.
Set individual timeouts on each dependency fetch (e.g., 2-5 seconds) and a hard limit on the total composite response (e.g., 10-15 seconds). Return partial data if some fetches timeout rather than failing everything. Use circuit breakers to stop retrying failing dependencies.
Not directly—webhooks are for push notifications. However, you can build event-driven systems where changes to component resources trigger recalculation of composite views, which are then cached for fast retrieval.