Private, cross-account GraphQL APIs with AppSync Merged APIs

In the realm of distributed systems and secure data sharing, GraphQL has become a valuable option for engineers.

AppSync, an AWS GraphQL offering, has recently released two very promising features: Private and Merged APIs:

• Private APIs restrict access to GraphQL APIs to clients within a private network and allow access to principals, such as AWS Accounts, VPCs or on-premises data centres. Introducing Private APIs on AWS AppSync | Amazon Web Services

• Merged APIs enable teams to merge resources (types, data sources, functions, resolvers) from multiple sources AppSync APIs into a single, consolidated and unified AppSync endpoint. Introducing Merged APIs on AWS AppSync | Amazon Web Services

This article provides a step-by-step guide to combining the two releases and exposing two private AppSync APIs through a public AppSync Merged API, providing the benefits of both releases.

Architecture

The architecture involves four accounts:

• AccountManagement: the account responsible for managing the AWS Organizational Units (OUs) via AWS Organizations.

• AccountA: hosting a private GraphQL API handling generic products.

• AccountB: hosting a private GraphQL API handing orders.

• AccountMerge: hosting the public merged GraphQL API.

The private GraphQL APIs will be shared with the public-facing API via Resource Access Manager (RAM).

0. Prerequisites

0.1 Setup Organizations

Before you can start creating the APIs, we must structure our cross-accounts setup.

• Create/reuse an AWS account responsible for managing AWS Organizations, called AccountManagement.

• In the same account, go to AWS Organizations and create an Organization.

• Start adding or inviting AWS accounts.

• Create/invite AccountA, AccountB and AccountMerge similarly.

• Optionally, you can place the accounts under Organizational Units (OUs) for better management.

• The Organizational structure should look as this:

For tutorials/troubleshooting on AWS Organizations (out of the scope of this article), please refer to the following: Tutorial: Creating and configuring an organization Access a member account created with AWS Organizations

0.2 Share resources

One last step is to enable sharing on this account. This step is required as I will be sharing private AppSync APIs via Resource Access Manager (RAM), a service that simplifies the process of sharing resources among AWS accounts. To enable resource sharing within your Organization:

• Open the Settings page in the AWS RAM console.

• Choose Enable sharing with AWS Organizations, and then choose Save settings.

Sharing your AWS resources

Let’s now follow the steps to create two private APIs and share them with the public Merge API.

1. Create a Product, Private AppSync API

Let’s now create a simple Product API. This will be a private AppSync endpoint, as it can only be accessed by VPC.

• Go to AccountA.

• Go to AppSync and Create an API.

• Create a Product API in AppSync. This starts with the Create API Wizard, which has four steps.

1.1 Select API Type

Select GraphQL APIs and Design from scratch.

1.2 Specify API metadata

Add the API name and select “Use private API features” and then “Next”.

1.3 Specify GrapQL resources

Create a GrapthQL type backed by a DynamoDB. The table is based on a Product model which four fields (id, title, description and createdAt) and a primary key. Click “Next”.

1.4 Review and create

Finally, review the wizard data and click "Create API”.

That’s it. A new private GraphQL API is not created. The next step is to share it with the public Merge API account.

2. Share the Product API

To share the API, we will use the RAM service. It is a cool and underestimated service that allows you to share AWS resources across multiple accounts in a controlled and secure manner. Essentially we will create a shared resource, which refers to an AWS service or component (e.g. an AppSync API…) that can be accessed and utilized by multiple AWS accounts or users within an organization. Let’s see how.

• Take note of the AWS Account id for the AccountMerge one.

• In the same account (AccountA), go to RAM.

• Click on “Create resource share”, which will start a wizard.

The wizard consists of 4 steps:

2.1 Specify resource share details

This step requires you to provide a name for the resource share and the resource itself. You can find the resource by filtering the search and searching for “AppSync GraphQL APIs”. Since RAM is a regional service, ensure you are in the same region as you created the AppSync API. If so, the API will appear in the resources list. Select it and click “Next”. The below pictures summarize the sub-steps:

2.2 Associate managed permissions

This important step specifies which actions principals can perform on shared resources.

• Click the “Create a customer-managed permissions” button.

• This opens a new tab where you can define which actions the principals can perform on a resource type in a resource share. Provide a name (e.g. AWSRAMAssociatedMergedAPIAccess) and select “All actions”. This is needed as the accounts’ Merge API must have the appsync:AssociateMergedGraphqlApi access level to correctly associate the private API with the Merge one.

• Finally, click the “Create a customer managed permissions” button in the new tab. The below picture summarizes the described flow:

• Now, back to the Create share resource tab, select the newly created customer managed permission and click “Next”.

2.3 Grant access to principals

This step defines the principals that are allowed access to the shared resources. Principals can be part of the same Organization (recommended) or not.

• Click “Allow sharing only within your organization”.

• Grab the AccountMerge account id and paste it into the input field.

• Click “Add”.

• Select the Principal below

• Click “Next”.

The below picture gives an overview of the flow:

2.4 Review and create

The last step is to review and finalize the Create resource share wizard; do so and click the Create resource share button.

3. Create an Order, Private AppSync API

The second private AppSync API to be created is about orders. You should repeat the same steps as section 2 but apply for an Orders API.

• Go to AccountB.

• Go to Appsync and Create an API.

• Follow the steps in Section 1, but. This time, you should create an Order model. An example would be three fields (id, quantity, productId), with a partition key for the order id (id field) and a global secondary index to query products.

• Finalize the wizard and provision the API.

By the end of this step, you must have an Orders API similar to the below:

4. Share the Order API

Now you must repeat the same steps in section 2, but instead, you need to share the orders API with the AccountMerge. This is the account hosting the Merge API, which we will create in the next section.

The shared resource should look like this:

Now comes the time to glue the two APIs into a single, unified Merge API.

5. Create the Merged API

Finally, it is time to put all pieces together. The goal is to create a public-facing AppSync API to merge both the Products and Orders private APIs. To do so:

• Go to the AccountMerge account.

• Go to AppSync.

• Create an API and start the wizard.

5.1 Select API Type

This time, we must select “Merged APIs” and click “Next”.

5.2 Specify API metadata

• Provide a name (e.g. MergedProductsAndOrdersAPI)

• Choose “Create and use a new service role”, as the new merged API requires an IAM role for AWS AppSync to access the imported source API resources at runtime securely.

• Click “Next”.

5.3 Select Sources API

This step allows you to associate the private API created in sections 1 (Products) and 3 (Orders).

• As they are located in different AWS accounts, click the “Add Source API” button with the “APIs from other AWS accounts” area.

• As we shared both private APIs in sections 2 and 4, they are now visible in this modal. Select them and click “Add Source APIs”

• Now that Source APIs have been chosen, click “Next”.

5.4 Select authorization mode

This step requires you to select the authorization mode to protect the Merged API with.

• For simplicity, we choose “API key”.

• Click “Next”.

More authorizations mode can be seen here: Merged APIs

5.5 Review and create

Finally, review the wizard data and click “Create API”. Now it is time to test the API.

6. Testing the API

To test the API, we can use the Query editor. Already from there, you can appreciate the result of this merged API:

Mutations, queries and subscriptions of both APIs have been merged!

Nevertheless, if you now try, for instance, to create a new product, you will encounter this issue:

Not authorized to perform: appsync:SourceGraphQL on resource arn:aws:appsync:<region>:<account_id>:apis/<api_id>

To fix this, we must modify the Merged API execution IAM role created during its wizard.

• Go to your Merged API.

• On the left side, click Settings.

• On the API menu, you will find the execution role link; click it.

• You will land in the IAM role. Here, you have complete freedom in the way you want to allow the permission. This is one example:

    {
        "Effect": "Allow",
        "Action": [
            "appsync:SourceGraphQL"
        ],
        "Resource": [
            "arn:aws:appsync:<REGION>:<ACCOUNT_ID>:apis/<APPSYNC_API_ID>/types/*/fields/*"
        ]
    }

• Save the role.

• Go back now to the query editor, and this time both creation of products, orders and listing works.

7. Conclusion

I hope you reached the end of this guide! Congrats.

This article provided a comprehensive guide on creating private GraphQL APIs using AWS AppSync and then merging them into a single public API. By leveraging the features of private APIs and the AppSync Merge API, organizations can address challenges related to API security and cross-team collaboration. This approach enables the consolidation of multiple private APIs into a unified endpoint, offering the benefits of both private access and centralized management.