Front-End Web & Mobile

AWS AppSync Merged APIs Best Practices: Part 1 – Cross Account Merged APIs with AWS Resource Access Manager

AWS AppSync is a serverless GraphQL service which makes it easy to create, manage, monitor and secure your GraphQL APIs. In the previous blog post, we announced the launch of Merged APIs for AWS AppSync. Merged APIs enable teams to merge resources, including types, data sources, functions, and resolvers, from multiple source AppSync APIs into a single, unified AppSync endpoint. In conjunction with the launch of Merged APIs, AWS AppSync has also integrated with AWS Resource Access Manager (AWS RAM) to provide a simple and streamlined way of configuring a Merged API composed of source APIs that are owned by multiple AWS accounts.

Overview of Using AWS RAM for Sharing AppSync APIs

AWS RAM helps you securely share your resources across AWS accounts, within your organization or organizational units (OUs), and with IAM roles and users for supported resource types. You can now use AWS RAM to share AppSync APIs with AWS accounts both inside and outside your organization as well as to specific IAM roles and users within a given AWS Account.

Consider an example where Account A is owned by the ‘Book Recommendations’ service team, and they want to enable access to the book recommendations data as part of the Book Reviews Merged API. The Book Reviews Merged API was created by a different team using Account B as part of the example in the previous blog. The diagram below shows the process of sharing a Recommendations source API in Account A with another account, Account B, in order for the owner of Account B to be able associate it within the Book Reviews Merged API.

Cross account AppSync API sharing with AWS RAM

Figure 1 : Cross account AppSync API sharing with AWS RAM

The first step of resource sharing in AWS RAM is creating a resource share. A resource share contains the following:

  1. One or more AWS resources to be shared, such as an AppSync API
  2. A list of one or more principals, such as AWS accounts, IAM users, or IAM roles, to whom access is being granted.
  3. A managed permission for each resource type included in the resource share. Managed permissions define the set of conditions and actions that a principal can perform on the AWS resource that has been shared using AWS RAM.

Managed Permissions Provided for Sharing AppSync Resources

When sharing access to an AppSync resource in AWS RAM, AppSync provides three different managed permissions that you can use for sharing.

  1. AWSRAMPermissionAppSyncSourceApiOperationAccess: The default AWS managed permission that’s added when sharing an AWS AppSync API in AWS RAM if no other managed permission is specified. This managed permission is used for sharing a source AWS AppSync API with a Merged API owner. This managed permission includes the permission for appsync:AssociateMergedGraphqlApi on the source API as well as the appsync:SourceGraphQL permission required to access the source API resources during query execution.
  2. AWSRAMPermissionAppSyncMergedApiOperationAccess: You may want to use this managed permission when you want the source API owner to be able to configure the Merged API directly rather than having the Merged API owner be in charge of managing the associations. This managed permission will give the source API the ability to configure the Merged API including the ability to associate any source APIs owned by the target principal to the Merged API and to read and update the source API associations of the Merged API. Otherwise, when you use the default managed permission, only the Merged API owner can configure the associations.
  3. AWSRAMPermissionAppSyncAllowSourceGraphQLAccess: This managed permission allows the appsync:SourceGraphQL permission to be used with an AWS AppSync API. It is intended to be used for sharing a source API with a Merged API owner for only runtime access. In contrast to the default AWS managed permission, this managed permission does not allow the target principal to associate the source API to a Merged API that it owns.

Customer Managed Permissions in AWS RAM

Along with the three AWS managed permissions provided by AppSync, AppSync allows customers to define their own customer managed permissions in AWS RAM itself. When defining a customer managed permission, you can add additional conditions to the policy as well as define the resource access permissions for an AppSync API. For a Merged API, at a minimum you need to make sure that the appsync:SourceGraphQL action on any source API is shared to the Merged API account or Merged API execution IAM role specifically for the source API to be accessible at runtime. For more on customer managed permissions, see the AWS RAM documentation.

Associating the Cross Account Source API for Book Recommendations

In this blog, we will further build on the example from the previous blog post in order to add an additional source API for book recommendations from another AWS account to the Book Reviews Merged API utilizing resource sharing provided by AWS Resource Access Manager.

Creating the Recommendations Source API

  • In the first step, we will create the source API for book recommendations in a different AWS Account than the one you used to create the Book Reviews Merged API. Login to the second account for creating this source API.
  • Navigate to the AppSync console and click on Create API . In Step 1 of the API creation wizard select GraphQL APIs option, Design from scratch and click Next.

Source API Creation

  • We add contact information for the Book Recommendations Team as in the following screenshot.

Recommendations Contact

  • We generate the Recommendation type backed by Dynamo DB using the model seen in the following screenshot.

Recommendation Type

  • Finally, accept the creation to complete creating the source API.
  • Navigate to the settings page and note down the API ID of the Recommendations API to be used in RAM sharing.

Creating the Resource Share

  • Next, now that the Recommendations API is created, we copy the API ID from the settings page and navigate to the AWS RAM console. Click the Create Resource Share button in the top right-hand corner to begin our share of this source API.
  • In Step 1, we name the resource share we are creating, select AppSync GraphQL APIs from the resource type drop down, and search for the Recommendations API using the API ID we noted above.

Resource share

  • In Step 2, we configure the managed permission that will be used for the AppSync:Apis in this resource share. In this example, we will use the default AWS managed permission: AWSRAMPermissionAppSyncSourceApiOperationAccess.

Managed Permissions

  • In step 3, we grant access to the AWS account principal which is the owner of the Book Reviews Merged API.

Grant Access

  • Click Add and Click Next to move to the final step
  • Finally, we confirm our selections and create the resource share.

Accepting the Resource Share Invitation

When a resource share is created, it generates an invitation to the target principal to accept the resource sharing, if the principal is external to your AWS Organization. Resource sharing to another principal within the same AWS Organization results in automatic acceptance of the resource share invitation.

  • In order to accept a resource share invitation, login to the account of the target principal and navigate to the AWS RAM console.
  • Under the Shared with Me Resource Shares menu you should find a new resource share which you can accept using the Accept resource share button.
  • Once accepted, the Recommendations API should now be visible in the Shared Resources list.
  • Note: In RAM, you have 12 hours to accept the resource share invitation or else it will not be able to be processed successfully.

Associating the Cross Account Source AppSync API using the AppSync Console

Now that the Recommendations API has been successfully shared within AWS RAM, it should be available to be added as a source API of the Book Reviews Merged API.

  • Login to the original account used to create the Book Reviews Merged API. Navigate to this API in the AppSync console.
  • In the Source APIs table, click the Add Source APIs button.
  • In the APIs from Other Accounts table, again click the Add Source APIs button to bring up the list of source APIs that have been shared to your account using AWS RAM.
    • Choose the RecommendationsAPIthat you shared previously and click the Add button to add this source to the existing Merged API.

add source apis

  • Now, the source API is added to the Book Reviews Merged API and merged into the unified endpoint!

Challenge

For your own challenge, you can try merging the Recommendations API data to the Users, Books, and Authors API data by adding additional fields to the Recommendations type in these source APIs and implementing resolvers that return the corresponding type given the keys stored in the BookRecommendationsTable. The previous blog post is a good reference for how to implement these field resolvers. You can also test the RecommendationsAPI independently and within the Merged API using the methods we discussed in the previous blog.

Removing Access to the Recommendations API

If at some point the resource share containing the Recommendations API is removed in RAM, the Book Reviews Merged API will still include it as an associated source API. However, runtime access to resolvers merged from the Recommendations API will no longer be authorized, returning a GraphQL error in the response. In order to remove the Recommendations API, the Recommendations API owner can disassociate it at any time using the console or the DisassociateMergedGraphqlApioperation provided by AppSync.

Recap

In this blog, we successfully completed the following:

  1. Created a source AppSync API for book recommendations with a type backed by a DynamoDB table.
  2. Created a resource share in AWS RAM and added the recommendations AppSync API to the resource share with the default permissions: AWSRAMPermissionAppSyncSourceApiOperationAccess
  3. Invited the AWS account which owns the Book Reviews Merged API to the resource share.
  4. Accepted the resource share invitation to allow the sharing of the Recommendations API.
  5. Successfully added the Recommendations API as a source API in the Book Reviews Merged API.

Cleanup

  1. Navigate to AppSync console in the AWS account containing the Recommendations API, Select RecommendationsAPI, click Delete, confirm the API Name and click Delete again**.**
  2. Navigate to DynamoDB console, select BookRecommendations table, click Delete , select confirm and click Delete again.
  3. Navigate to the AWS RAM console in the AWS account containing the Recommendations API. Select Resource Shares under the Shared by Me menu. Select the RecommendationsAPIResourceShare and click Delete.
  4. Navigate to AppSync console in the AWS account containing the Book Reviews Merged API, Select Books Review Merged API, click Delete , confirm the API Name and click Delete again**.**
  5. Repeat step 3 for all the Source APIs as well.
  6. Navigate to DynamoDB console, Select tables associated with Source APIs (BooksTable, AuthorsTable, ReviewsTableand UsersTable) , click Delete , select confirm and click Delete again.

Get started today!

AWS AppSync Merged APIs feature is generally available in all AWS regions where AWS AppSync is available today. You can refer to AWS Regional Services List to find out the regions where AppSync is available. To learn more about Merged APIs, refer to the AppSync documentation or visit the AppSync product page for more general information on AWS AppSync. We can’t wait to see what you will build!

About the author

Nicholas is a Senior Software Engineer who has been working on AWS AppSync for the past 3 years. He spends his work days focused on improving GraphQL query execution performance and weekends roaming around San Francisco with his dog Pippa.