Unifying Microservice GraphQL with AWS AppSync Merged API - Distributed Team Development in Practice
Merge GraphQL APIs developed and deployed independently by multiple teams into a single endpoint. Learn strategies for avoiding schema conflicts and designing authentication.
Why Merged API Is Needed
In a microservices architecture where multiple teams develop GraphQL APIs, the frontend needs to send requests to multiple endpoints, increasing client-side complexity. Merged API solves this problem by consolidating multiple source APIs into a single endpoint. The User team's User API, the Orders team's Order API, and the Products team's Product API can each be developed and deployed independently, while the frontend accesses everything through a single GraphQL endpoint. Unlike REST-based API aggregation with API Gateway, the integration happens at the GraphQL schema level, so cross-service queries can be executed in a single request.
Source API Design and Independent Deployment
Each team develops an independent AppSync API as a source API. Schemas, resolvers, and data sources are managed per source API, and teams can freely deploy and update their own APIs. Source API updates are automatically reflected in the Merged API. Schema conflicts (same-named Query fields, same-named type definitions) are detected during merging and reported as errors. To avoid conflicts, it is recommended that teams agree on schema naming conventions in advance, using namespace-like prefixes (user_, order_) or managing common type definitions as a shared schema.
Authentication Strategy
Set the default authentication method (Cognito user pools, IAM, API keys, Lambda authorizers) at the Merged API level. Additional authentication methods can be configured per source API, and source API authentication can be applied to specific fields. For example, you can set Cognito as the default authentication for the Merged API while adding IAM authentication at the source API level for admin-only Mutations. The @aws_auth directive controls field-level authentication, allowing you to expose specific fields only to certain Cognito groups. For more detailed coverage of microservices, you can also check out related books on Amazon.
Merged API Pricing and Limitations
Merged API pricing is the same as regular AppSync APIs, at approximately $4.00 per million requests for queries and mutations. There are no additional charges for Merged API itself, but there is a limit on the number of source APIs (default 10), and a limit increase request is needed for large-scale microservice environments. When source API resolvers invoke Lambda, Lambda charges are billed to the source API's account. Enabling caching on the Merged API caches query results across source APIs, reducing backend call counts.
Summary
AppSync Merged API is a service that consolidates multiple teams' GraphQL APIs into a single endpoint. It maintains independent deployment for each team while providing a simple single endpoint to the frontend. It is the standard pattern for adopting GraphQL in a microservices architecture.