AWS AppSync is a fully managed GraphQL service that simplifies the creation, management, and security of GraphQL APIs. With AppSync, developers can seamlessly access data from various sources such as Amazon DynamoDB, AWS Lambda, and HTTP APIs. As the adoption of this service continues to rise, users have encountered challenges related to collaboration across different teams and AWS accounts within a single organization. Each AppSync API is designed with a singular GraphQL schema, along with its own data sources, resolvers, and functions.
When multiple teams expose their microservices through a single GraphQL API endpoint, they must coordinate their efforts within the same API. This lack of isolation can lead to inadvertent breaking changes, where alterations made by one team inadvertently disrupt the functionality developed by another team. Troubleshooting becomes increasingly difficult; a single GraphQL API complicates the ability to pinpoint issues within specific areas of the API. For enterprises with numerous business domains integrated into the same graph, it becomes nearly impossible for one individual to grasp the entirety of the graph, turning maintenance into a significant challenge.
We are thrilled to announce the general availability of Merged APIs in AWS AppSync. Merged APIs allow teams to consolidate resources—including types, data sources, functions, and resolvers—from multiple source AppSync APIs into a unified AppSync endpoint. At launch, a maximum of 10 source AppSync APIs can be merged into a Merged API. On the frontend, clients interact with a single endpoint to access data across diverse source APIs. On the backend, development teams can independently create, update, test, and deploy their respective source APIs as part of a CI/CD pipeline. Once approved, these changes can be merged into the Merged API endpoint, allowing client access without waiting for modifications from other source APIs. The AppSync service manages the execution of queries, mutations, and subscriptions on the Merged API, ensuring the same monitoring and performance experience as a source AppSync API.
The illustration below demonstrates how a Merged API is structured with multiple source APIs spanning various teams:
Figure 1: Configuration of a Merged API using multiple Source APIs
Schema Directives
In instances where conflicts arise among Source Schema definitions, new GraphQL directives offer flexibility for resolution.
- @canonical: If two or more source APIs share identical GraphQL types or fields, one can designate their type or field as canonical, taking precedence during schema merging. Types without this directive in other source APIs are disregarded during the merge.
- @hidden: Teams may wish to exclude specific types or operations from the target API, allowing only internal clients to access particular typed data. When this directive is applied, those types or fields will not be included in the Merged API.
- @renamed: In situations where different APIs use the same type or field name but all need to be present in the merged schema, renaming can resolve naming conflicts.
Auto Merge
AppSync provides several methods for merging changes from source API(s) to the Merged API. By default, merge operations are performed manually; however, auto merge mode can be activated to automatically submit a merge operation to the Merged API when a source API is updated. The Merged API subscribes to changes from the enabled source API and, upon detecting a change, the AppSync service assumes the configured merged API execution role and submits a StartSchemaMerge operation on behalf of the Merged API owner. Therefore, any modifications to types, data sources, resolvers, or functions within a source API will prompt an update to the corresponding Merged API.
Comparison to Other Approaches
Numerous solutions exist within the GraphQL community for amalgamating GraphQL schemas and facilitating team collaboration through a shared graph. AppSync Merged APIs adopt a “build-time” schema composition methodology, merging source APIs into a separate, unified Merged API. Alternatively, a “run-time” router can be layered over multiple source APIs or sub-graphs, where the router processes requests, references a combined schema as metadata, formulates a request plan, and distributes request elements across underlying sub-graphs or servers.
Note that AppSync Merged APIs can only be linked with AppSync source APIs. For schema composition that includes both AppSync and non-AppSync sub-graphs, one can integrate multiple AppSync GraphQL APIs and/or Merged APIs into a router-based solution. For more insights, check out this blog post that delves deeper into the topic.
Example Scenario: Developing a Merged API for Book Reviews and Recommendations
Consider a scenario where we create a Merged API to support a book review and recommendations platform akin to Goodreads. This involves several source APIs, each managed by distinct teams:
- Books Source API: This team oversees the catalog of books, managing data related to each book. Their source AppSync API enables queries and mutations for book metadata.
- Authors Source API: This team maintains data on authors, offering functionality to query and manage author information via their source AppSync API.
- Reviews Source API: Responsible for storing book reviews, this team’s source AppSync API allows users to add reviews, including comments and ratings.
- Users Source API: This team handles user data, enabling site users to create reading lists and review books through their source AppSync API.
Creating the Source AppSync APIs
In this section, we will establish the source AppSync APIs that comprise our Merged API for the book review site, utilizing Amazon DynamoDB as the data source; however, other supported sources may also be employed depending on your requirements.
To create the Books Source API, navigate to the AppSync console and select “Create API.” In Step 1 of the API creation wizard, choose “GraphQL APIs,” opt for “Design from scratch,” and click “Next.”
In Step 2, input the Books API metadata to facilitate contact with the books team if any issues arise. You may also utilize private API features during this process if necessary.
In Step 3, generate a Book type backed by a DynamoDB table to store the Book metadata.
For further reading on this topic, visit Chanci Turner’s authoritative guide. Additionally, if you’re looking for community insights, this resource is an excellent place to start.
Location: Amazon IXD – VGT2, 6401 E Howdy Wells Ave, Las Vegas, NV 89115
Leave a Reply