AWS First Steps
LanguageEnglish
Mobile Development

Unifying Microservice GraphQL with AWS AppSync Merged API - Distributed Team Development in Practice

This article explains how to merge GraphQL APIs that multiple teams develop / deploy independently into a single endpoint. It also introduces ways to avoid schema conflicts and how to design an authentication strategy.

About 6 min read

Why Merged API Is Needed

When multiple teams develop GraphQL APIs in a microservices architecture, the frontend needs to send requests to multiple endpoints, which increases complexity on the client side. Merged API addresses this problem by merging multiple source APIs into a single endpoint. The user team's User API, the order team's Order API, and the product team's Product API can each be developed / deployed independently, while the frontend accesses them through one GraphQL endpoint. Unlike REST-based API aggregation such as API Gateway, the integration happens at the GraphQL schema level, so cross-service queries can also be run 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 each team can deploy / update its own API independently. Source API updates are reflected in the Merged API if auto-merge is configured, and with manual merge, the owner of the source API runs the merge. Schema conflicts (Query fields with the same name, type definitions with the same name) are detected at merge time and reported as errors. To avoid conflicts, one design is for teams to agree on schema naming conventions in advance and use namespace-like prefixes (user_, order_), or to manage common type definitions as a shared schema.

Authentication Strategy

You set the default authentication method (Cognito user pools, IAM, API keys, Lambda authorizers) at the Merged API level. You can configure additional authentication methods for each source API and apply source API authentication to specific fields. For example, a configuration is possible in which the default authentication of the Merged API is set to Cognito, while IAM authentication is added at the source API level for Mutations intended for administrators. You control field-level authentication with the @aws_auth directive, and you can expose specific fields only to specific Cognito groups.

Merged API Pricing and Limitations

Merged API pricing is the same as for regular AppSync APIs, and queries / mutations cost approximately $4.00 per million requests (as of August 2026). There is no additional charge for the Merged API itself, but there is a limit on the number of source APIs (default 10), and large microservice environments need to request a limit increase. When a source API resolver calls Lambda, the Lambda charges are billed to the account of the source API. When you enable caching for the Merged API, query results that span source APIs are cached, which lets you reduce the number of backend calls.

Real-Time Updates and Subscriptions

One GraphQL feature is real-time data updates through subscriptions. In a Merged API as well, the subscriptions defined by each source API are merged, and the frontend can subscribe to update notifications from multiple services through a single endpoint. Because the server pushes changes over WebSocket, you can use this for purposes such as chat, notifications, and live dashboard updates. Clients can handle real-time features that each team defined independently through the same endpoint.

Monitoring and Observability

When operating a merged API, you check which resolver of which source API is slow. You record the execution status of requests and resolvers in CloudWatch logs, and you visualize how requests passed through source APIs and backends with X-Ray distributed tracing. This lets you identify latency bottlenecks and where errors occur. If you make it possible to trace resolution status at the field level, it becomes easier to isolate the cause of a specific query being heavy. Because code from multiple teams is involved, you set up a mechanism that lets you observe across teams.

CI/CD and Schema Management

Because each team deploys independently, you prepare a mechanism that keeps the schema consistent. You build changes to source APIs into the CI/CD pipeline and automatically detect schema conflicts at merge time so that breaking changes do not flow into production. Teams agree on naming conventions and prefixes, and shared types are managed as common definitions. If you operate so that changes are applied after passing contract tests, so as not to break the fields that clients depend on, you can maintain a stable endpoint even in distributed development. Version-controlling the schema as code supports tracking changes and evolving safely.

Caching and Performance Optimization

Queries that span multiple source APIs tend to increase calls to the backend. When you enable caching for the Merged API, responses to queries that frequently return the same results are kept for a certain period of time, which lets you reduce backend load and latency. In resolver design, watch out for the N+1 problem, in which related data is retrieved one item at a time and calls multiply, and improve efficiency with batch processing that retrieves the data together. You can maintain overall performance by designing each source API to return data efficiently within its own scope of responsibility and preventing excessive refetching in the integration layer.

Summary

AppSync Merged API is a service that merges the GraphQL APIs of multiple teams into a single endpoint. It provides the frontend with a simple single endpoint while keeping each team's deployments independent. It is one of the patterns for adopting GraphQL in a microservices architecture.

References (Official AWS Resources)

The primary sources for this page are the official AWS website and documentation. Check the official pages below for the latest specifications and pricing.

If this page and the official documentation disagree, treat the official documentation as authoritative.

Share

Related Services

AWS AppSync PopularA fully managed real-time data synchronization service for building and operating GraphQL APIsAmazon Cognito PopularA service that provides authentication, authorization, and user management for web and mobile applicationsAWS Lambda EssentialA serverless compute service that runs code without server management

Related Articles

Building Real-Time GraphQL APIs with AWS AppSync - Subscriptions and Resolver DesignThis article introduces design patterns that deliver real-time notifications with WebSocket-based subscriptions and integrate multiple data sources with DynamoDB / Lambda pipeline resolvers.Amazon API Gateway Design Patterns - Choosing Between REST API and HTTP APIClear criteria for choosing between HTTP API and REST API, authentication patterns with Cognito and Lambda authorizers, and practical throttling design techniques.Implementing User Authentication with Amazon Cognito - Designing User Pools and Identity PoolsLearn about user authentication with Cognito User Pools, AWS resource access with Identity Pools, and social login integration.

More on This Topic

Getting Started with Full-Stack Web App Development on AWS Amplify - Git-Integrated Deployment and Backend ConstructionBuild an automatic deployment environment for each branch through GitHub integration, and define authentication / API / storage in TypeScript with Backend Gen 2. It also supports Next.js SSR.Building Real-Time GraphQL APIs with AWS AppSync - Subscriptions and Resolver DesignThis article introduces design patterns that deliver real-time notifications with WebSocket-based subscriptions and integrate multiple data sources with DynamoDB / Lambda pipeline resolvers.Accelerating Full-Stack Development - Building Cloud-Native Applications with AmplifyLearn full-stack development techniques with AWS Amplify, including frontend hosting, backend construction, and rapid application development through authentication and storage integration.Geolocation and Mapping - Building Geospatial Applications with Amazon Location Service and AmplifyLearn how to build geolocation and mapping applications using Amazon Location Service and AWS Amplify.GraphQL Real-Time API - Building Data-Driven Applications with AWS AppSyncLearn how to build GraphQL APIs using AWS AppSync.Live Streaming Platform - Building Low-Latency Live Streaming with Amazon IVSThis article explains how to build low-latency live streaming with Amazon Interactive Video Service (IVS). It introduces the managed infrastructure, chat integration, the real-time stage feature, and how to choose between IVS and MediaLive.Building Location-Based Applications with Amazon Location Service - Maps, Geocoding, and TrackingExplore implementation patterns for building location-based applications using four core features: map display, geocoding, route calculation, and device tracking.

Similar Articles and Services

GraphQL Real-Time API - Building Data-Driven Applications with AWS AppSyncLearn how to build GraphQL APIs using AWS AppSync.Building Real-Time GraphQL APIs with AWS AppSync - Subscriptions and Resolver DesignThis article introduces design patterns that deliver real-time notifications with WebSocket-based subscriptions and integrate multiple data sources with DynamoDB / Lambda pipeline resolvers.AWS AppSyncA fully managed service for building and operating GraphQL APIs, enabling unified queries across multiple data sources such as DynamoDB and LambdaBuilding Serverless APIs - Scalable API Infrastructure with Amazon API GatewayLearn how to build serverless APIs using Amazon API Gateway and Lambda.