From dc51c9ff526cf9551f976e7f84cfbf8cabd40006 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Mon, 26 Aug 2024 13:53:44 -0400 Subject: [PATCH 01/17] feat(data): appsync apollo extensions --- .../aws-appsync-apollo-extensions/index.mdx | 294 ++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx new file mode 100644 index 00000000000..411c6fd6403 --- /dev/null +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -0,0 +1,294 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'AWS AppSync Apollo Extensions', + description: + 'AWS AppSync Apollo Extensions', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export function getStaticPaths() { + return getCustomStaticPath(meta.platforms); +} + +export function getStaticProps(context) { + return { + props: { + platform: context.params.platform, + meta + } + }; +} + +AWS AppSync Apollo Extensions provides a seamless way to connect to your AWS AppSync while using the Apollo client. Apollo client is an open-source GraphQL client. + + + +To learn more about Apollo, see https://www.apollographql.com/docs/ios/. + + + + + + +To learn more about Apollo, see https://www.apollographql.com/docs/kotlin. + + + +### Features + +AWS AppSync Apollo Extensions provide AWS AppSync authorizers to be used with the Apollo client to make it simple to configure runtime interceptors and apply the correct authorization payloads to your GraphQL operations. + +The Amplify library provides components to facilitate configuring the authorizers with Apollo client by providing configuration values to connect to your Amplify Data backend. + + + +### Install the AWS AppSync Apollo library + +Add AWS AppSync Apollo Extensions into your project using Swift Package Manager. + +Enter its GitHub URL (`https://github.com/aws-amplify/aws-appsync-apollo-extensions-swift`), select **Up to Next Major Version** and click **Add Package** + +* Select the following libraries: + * **AWSAppSyncApolloExtensions** + + + +### Connecting to AWS AppSync with Apollo client + +AWS AppSync supports the following authorization modes (https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html) + +#### API_KEY + + + +```swift +import AWSAppSyncApolloExtensions + +let authorizer = APIKeyAuthorizer(apiKey: "[API_KEY]") +let interceptor = AppSyncInterceptor(authorizer) +``` + + + + + +```kotlin +val authorizer = ApiKeyAuthorizer("[API_KEY]") +val interceptor = AppSyncInterceptor(authorizer) +``` + + + +#### AMAZON_COGNITO_USER_POOLS + + + +If you are using Amplify Auth, you can create a method that retrieves the Cognito access token + +```swift +import Amplify + +func getUserPoolAccessToken() async throws -> String { + let authSession = try await Amplify.Auth.fetchAuthSession() + if let result = (authSession as? AuthCognitoTokensProvider)?.getCognitoTokens() { + switch result { + case .success(let tokens): + return tokens.accessToken + case .failure(let error): + throw error + } + } + throw AuthError.unknown("Did not receive a valid response from fetchAuthSession for get token.") +} +``` + +Then create the AuthTokenAuthorizer with this method. + +```swift +import AWSAppSyncApolloExtensions + +let authorizer = AuthTokenAuthorizer(fetchLatestAuthToken: getUserPoolAccessToken) +let interceptor = AppSyncInterceptor(authorizer) +``` + + + + +Create the AuthTokenAuthorizer with this method. + +```kotlin +let authorizer = AuthTokenAuthorizer(fetchLatestAuthToken: getLatestTokenFromAmplify) +``` + + + +You can provide your own custom `fetchLatestAuthToken` provider for **AWS_LAMBDA** and **OPENID_CONNECT** auth modes. + +#### AWS_IAM + + + +If you are using Amplify Auth, you can use the following method for AWS_IAM auth + +``` +import AWSCognitoAuthPlugin +import AWSAppSyncApolloExtensions + +let authorizer = IAMAuthorizer( + signRequest: AWSCognitoAuthPlugin.createAppSyncSigner( + region: "[REGION]")) +``` + + + + + +If you are using Amplify Auth, you can use the following method for AWS_IAM auth + +``` +val authorizer = IamAuthorizer { ApolloAmplifyConnector.signAppSyncRequest(it, "us-east-1") } +``` + + + +### Connecting Amplify Data to Apollo client + +Before you begin, you will need an Amplify Data backend deploy. To get started, see [Set up Data](/[platform]/swift/build-a-backend/data/set-up-data/). + +Once you have deployed your backend and created the `amplify_outputs.json`, you can use Amplify library to read and retrieve your configuration values with the following steps: + + + +1. Enter its GitHub URL (`https://github.com/aws-amplify/amplify-swift`), select **Up to Next Major Version** and click **Add Package** +2. Select the following libraries: + 1. **AWSPluginsCore** +3. Drag and drop the `amplify_outputs.json` file into your Xcode project. +4. Initialize the configuration with `try AWSAppSyncConfiguration(with: .amplifyOutputs)` + +The resulting configuration object will have the `endpoint`, `region`, and optional `apiKey.` The following example shows reading the `amplify_outputs.json` file from the main bundle to instantiate the configuration and uses it to configure the Apollo client for **API_Key** authorization. + +```swift +import Apollo +import ApolloAPI +import AWSPluginsCore +import AWSAppSyncApolloExtensions + +func createApolloClient() throws -> ApolloClient { + let store = ApolloStore(cache: InMemoryNormalizedCache()) + + // 1. Read AWS AppSync API configuration from `amplify_outputs.json` + let configuration = try AWSAppSyncConfiguration(with: .amplifyOutputs) + + // 2. Use `configuration.apiKey` with APIKeyAuthorizer + let authorizer = APIKeyAuthorizer(apiKey: configuration.apiKey ?? "") + let interceptor = AppSyncInterceptor(authorizer) + let interceptorProvider = DefaultPrependInterceptorProvider(interceptor: interceptor, + store: store) + // 3. Use `configuration.endpoint` with RequestChainNetworkTransport + let transport = RequestChainNetworkTransport(interceptorProvider: interceptorProvider, + endpointURL: configuration.endpoint) + + return ApolloClient(networkTransport: transport, store: store) +} +``` + + + +Depending on your authorization strategy defined on your schema, you can use the corresponding Authorizer. To read more about the strategies and their corresponding auth modes, see [Available authorization strategies](/[platform]/build-a-backend/data/customize-authz/#available-authorization-strategies). + + +Some common ones are + +* `publicAPIkey` strategy, `apiKey` authMode, **APIKeyAuthorizer** +* `guest` strategy, `identityPool` authMode, **IAMAuthorizer** +* `owner` strategy, `userPool` authMode, **AuthTokenAuthorizer** + +If you define multiple authorization strategies on a single model, you will have to create separate Apollo client instances for each Authorizer that you want to use in your app. + +### Downloading the AWS AppSync schema + +The schema is used by Apollo’s code generation tool to generate API code that helps you execute GraphQL operations. To retrieve your AWS AppSync schema: + + +1. Navigate to your API on the AWS AppSync console +2. On the left side, select Schema +3. When viewing your schema, there should a “Export schema” drop down. Select this and download the `schema.json` file. +4. Add this file to your project as directed by [Apollo Code Generation documentation](https://www.apollographql.com/docs/ios/code-generation/introduction) + + + +1. Navigate to your API on the AWS AppSync console +2. On the left side, select Schema +3. When viewing your schema, there should a “Export schema” drop down. Select this and download the `schema.json` file. +4. Add this file to your project as directed by [Apollo Code Generation documentation](https://www.apollographql.com/docs/ios/code-generation/introduction) + + +## Connecting to AWS AppSync real-time endpoint + +The following example shows how you can create an Apollo client that allows performing GraphQL subscription operations with AWS AppSync. + + + +``` +import Apollo +import ApolloAPI +import ApolloWebSocket +import AWSPluginsCore +import AWSAppSyncApolloExtensions + +func createApolloClient() throws -> ApolloClient { + let store = ApolloStore(cache: InMemoryNormalizedCache()) + let configuration = try AWSAppSyncConfiguration(with: .amplifyOutputs) + + // 1. Create your authorizer + let authorizer = /* your Authorizer */ + let interceptor = AppSyncInterceptor(authorizer) + + let interceptorProvider = DefaultPrependInterceptorProvider(interceptor: interceptor, + store: store) + let transport = RequestChainNetworkTransport(interceptorProvider: interceptorProvider, + endpointURL: configuration.endpoint) + + // 2. Create the AWS AppSync compatible websocket client + let websocket = AppSyncWebSocketClient(endpointURL: configuration.endpoint, + authorizer: authorizer) + // 3. Add it to the WebSocketTransport + let webSocketTransport = WebSocketTransport(websocket: websocket) + // 4. Create a SplitNetworkTransport + let splitTransport = SplitNetworkTransport( + uploadingNetworkTransport: transport, + webSocketNetworkTransport: webSocketTransport + ) + // 5. Pass the SplitNetworkTransport to the ApolloClient + return ApolloClient(networkTransport: splitTransport, store: store) +} +``` + + + + + +```kotlin +// Create the network transport +val networkTransport = WebSocketNetworkTransport.Builder() + .protocol(AppSyncProtocol.Factory(endpoint, authorizer)) + .build() + +// Use the network transport when creating the Apollo Client +val apolloClient = ApolloClient.Builder() + .subscriptionNetworkTransport(networkTransport) + .build() +``` + + From 14d3be9d3b1e4a1236321b4e56f9dba8ed5f44bc Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 13:29:05 -0400 Subject: [PATCH 02/17] Apply suggestions from code review Co-authored-by: josef --- .../aws-appsync-apollo-extensions/index.mdx | 21 +++++++------------ 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index 411c6fd6403..3feb5d91c6c 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -6,14 +6,7 @@ export const meta = { 'AWS AppSync Apollo Extensions', platforms: [ 'android', - 'angular', - 'flutter', - 'javascript', - 'nextjs', - 'react', - 'react-native', 'swift', - 'vue' ] }; @@ -66,7 +59,7 @@ Enter its GitHub URL (`https://github.com/aws-amplify/aws-appsync-apollo-extensi ### Connecting to AWS AppSync with Apollo client -AWS AppSync supports the following authorization modes (https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html) +AWS AppSync supports the following [authorization modes](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html) #### API_KEY @@ -141,7 +134,7 @@ You can provide your own custom `fetchLatestAuthToken` provider for **AWS_LAMBDA If you are using Amplify Auth, you can use the following method for AWS_IAM auth -``` +```swift import AWSCognitoAuthPlugin import AWSAppSyncApolloExtensions @@ -156,7 +149,7 @@ let authorizer = IAMAuthorizer( If you are using Amplify Auth, you can use the following method for AWS_IAM auth -``` +```kotlin val authorizer = IamAuthorizer { ApolloAmplifyConnector.signAppSyncRequest(it, "us-east-1") } ``` @@ -166,7 +159,7 @@ val authorizer = IamAuthorizer { ApolloAmplifyConnector.signAppSyncRequest(it, " Before you begin, you will need an Amplify Data backend deploy. To get started, see [Set up Data](/[platform]/swift/build-a-backend/data/set-up-data/). -Once you have deployed your backend and created the `amplify_outputs.json`, you can use Amplify library to read and retrieve your configuration values with the following steps: +Once you have deployed your backend and created the `amplify_outputs.json` file, you can use Amplify library to read and retrieve your configuration values with the following steps: @@ -221,14 +214,14 @@ If you define multiple authorization strategies on a single model, you will have The schema is used by Apollo’s code generation tool to generate API code that helps you execute GraphQL operations. To retrieve your AWS AppSync schema: -1. Navigate to your API on the AWS AppSync console +1. Navigate to your API on the [AWS AppSync console](https://console.aws.amazon.com/appsync/home) 2. On the left side, select Schema 3. When viewing your schema, there should a “Export schema” drop down. Select this and download the `schema.json` file. 4. Add this file to your project as directed by [Apollo Code Generation documentation](https://www.apollographql.com/docs/ios/code-generation/introduction) -1. Navigate to your API on the AWS AppSync console +1. Navigate to your API on the [AWS AppSync console](https://console.aws.amazon.com/appsync/home) 2. On the left side, select Schema 3. When viewing your schema, there should a “Export schema” drop down. Select this and download the `schema.json` file. 4. Add this file to your project as directed by [Apollo Code Generation documentation](https://www.apollographql.com/docs/ios/code-generation/introduction) @@ -240,7 +233,7 @@ The following example shows how you can create an Apollo client that allows perf -``` +```swift import Apollo import ApolloAPI import ApolloWebSocket From 48829bd2ed5f801c8b79b4e716ba12f40781ecec Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 14:17:58 -0400 Subject: [PATCH 03/17] fix: add to directory page --- src/directory/directory.mjs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index d8bcb643a59..a18308f9050 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -317,6 +317,9 @@ export const directory = { }, { path: 'src/pages/[platform]/build-a-backend/data/manage-with-amplify-console/index.mdx' + }, + { + path: 'src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx' } ] }, From b0ab45660dc0fbf0f801fbfc7432446958c7eb02 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 14:57:03 -0400 Subject: [PATCH 04/17] Apply suggestions from code review Co-authored-by: Matt Creaser --- .../data/aws-appsync-apollo-extensions/index.mdx | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index 3feb5d91c6c..aaf3378a4e8 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -121,7 +121,7 @@ let interceptor = AppSyncInterceptor(authorizer) Create the AuthTokenAuthorizer with this method. ```kotlin -let authorizer = AuthTokenAuthorizer(fetchLatestAuthToken: getLatestTokenFromAmplify) +val authorizer = AuthTokenAuthorizer { ApolloAmplifyConnector.fetchLatestCognitoAuthToken() } ``` @@ -224,7 +224,7 @@ The schema is used by Apollo’s code generation tool to generate API code that 1. Navigate to your API on the [AWS AppSync console](https://console.aws.amazon.com/appsync/home) 2. On the left side, select Schema 3. When viewing your schema, there should a “Export schema” drop down. Select this and download the `schema.json` file. -4. Add this file to your project as directed by [Apollo Code Generation documentation](https://www.apollographql.com/docs/ios/code-generation/introduction) +4. Add this file to your project as directed by [Apollo documentation](https://www.apollographql.com/docs/kotlin/advanced/plugin-recipes#specifying-the-schema-location) ## Connecting to AWS AppSync real-time endpoint @@ -273,14 +273,11 @@ func createApolloClient() throws -> ApolloClient { ```kotlin -// Create the network transport -val networkTransport = WebSocketNetworkTransport.Builder() - .protocol(AppSyncProtocol.Factory(endpoint, authorizer)) - .build() +val endpoint = AppSyncEndpoint("") +val authorizer = /* your Authorizer */ -// Use the network transport when creating the Apollo Client val apolloClient = ApolloClient.Builder() - .subscriptionNetworkTransport(networkTransport) + .appSync(endpoint, authorizer) .build() ``` From 18b7017c9f6bc8eb3bc3fa46800c6f5dceb85868 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 14:59:59 -0400 Subject: [PATCH 05/17] fix: mention introspection on swift schema section --- .../data/aws-appsync-apollo-extensions/index.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index aaf3378a4e8..de68ca5e36a 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -211,13 +211,16 @@ If you define multiple authorization strategies on a single model, you will have ### Downloading the AWS AppSync schema -The schema is used by Apollo’s code generation tool to generate API code that helps you execute GraphQL operations. To retrieve your AWS AppSync schema: +The schema is used by Apollo’s code generation tool to generate API code that helps you execute GraphQL operations. The following steps integrate your AppSync schema with Apollo's code generation process: 1. Navigate to your API on the [AWS AppSync console](https://console.aws.amazon.com/appsync/home) 2. On the left side, select Schema 3. When viewing your schema, there should a “Export schema” drop down. Select this and download the `schema.json` file. 4. Add this file to your project as directed by [Apollo Code Generation documentation](https://www.apollographql.com/docs/ios/code-generation/introduction) + +You can alternatively download the introspection schema using the [`fetch-schema`](https://www.apollographql.com/docs/ios/code-generation/codegen-cli#fetch-schema) command with the `amplify-ios-cli` tool. + From b8385173856367b1b233052d0426f817c6e5c3ab Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 15:06:22 -0400 Subject: [PATCH 06/17] fix: add android install and amplify data example --- .../aws-appsync-apollo-extensions/index.mdx | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index de68ca5e36a..c970e7eb493 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -44,6 +44,22 @@ AWS AppSync Apollo Extensions provide AWS AppSync authorizers to be used with th The Amplify library provides components to facilitate configuring the authorizers with Apollo client by providing configuration values to connect to your Amplify Data backend. + + +### Install the AWS AppSync Apollo library + +Add AWS AppSync Apollo Extensions dependency to your app/build.gradle.kts file: + +```kotlin title="app/build.gradle.kts" +dependencies { + // highlight-start + implementation("com.amplifyframework:aws-appsync-apollo-extensions-android:1.0.0") + // highlight-end +} +``` + + + ### Install the AWS AppSync Apollo library @@ -198,6 +214,27 @@ func createApolloClient() throws -> ApolloClient { + + + +Add Amplify AppSync Extensions dependency to your app/build.gradle.kts file: + +```kotlin title="app/build.gradle.kts" +dependencies { + // highlight-start + implementation("com.amplifyframework:amplify-appsync-apollo:1.0.0") + // highlight-end +} +``` + + + +```kotlin +Code Sample +``` + + + Depending on your authorization strategy defined on your schema, you can use the corresponding Authorizer. To read more about the strategies and their corresponding auth modes, see [Available authorization strategies](/[platform]/build-a-backend/data/customize-authz/#available-authorization-strategies). From 97e6cef920492d6458341312e2f077e5c00b2e55 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 15:09:27 -0400 Subject: [PATCH 07/17] fix: add android install and amplify data example --- .../data/aws-appsync-apollo-extensions/index.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index c970e7eb493..b2198f02caa 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -216,7 +216,6 @@ func createApolloClient() throws -> ApolloClient { - Add Amplify AppSync Extensions dependency to your app/build.gradle.kts file: ```kotlin title="app/build.gradle.kts" @@ -227,8 +226,6 @@ dependencies { } ``` - - ```kotlin Code Sample ``` From 43233ddb24ce86ae0b5f647723d077b0c59a3563 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 15:11:11 -0400 Subject: [PATCH 08/17] Update src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx --- .../data/aws-appsync-apollo-extensions/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index b2198f02caa..181f8f2cb40 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -53,7 +53,7 @@ Add AWS AppSync Apollo Extensions dependency to your app/build.gradle.kts file: ```kotlin title="app/build.gradle.kts" dependencies { // highlight-start - implementation("com.amplifyframework:aws-appsync-apollo-extensions-android:1.0.0") + implementation("com.amplifyframework:apollo-appsync:1.0.0") // highlight-end } ``` From 29de8ee1edd926942d7e63630da959685dd48497 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 15:11:55 -0400 Subject: [PATCH 09/17] Update src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx --- .../data/aws-appsync-apollo-extensions/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index 181f8f2cb40..fb5e64e6da5 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -221,7 +221,7 @@ Add Amplify AppSync Extensions dependency to your app/build.gradle.kts file: ```kotlin title="app/build.gradle.kts" dependencies { // highlight-start - implementation("com.amplifyframework:amplify-appsync-apollo:1.0.0") + implementation("com.amplifyframework:apollo-appsync-amplify:1.0.0") // highlight-end } ``` From ca27228b3fba3d5a0f3d2f457aa0c13d5e621a53 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 15:20:51 -0400 Subject: [PATCH 10/17] Update src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx --- .../data/aws-appsync-apollo-extensions/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index fb5e64e6da5..cbe0c481ddc 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -216,7 +216,7 @@ func createApolloClient() throws -> ApolloClient { -Add Amplify AppSync Extensions dependency to your app/build.gradle.kts file: +Add `apollo-appsync-amplify` dependency to your app/build.gradle.kts file: ```kotlin title="app/build.gradle.kts" dependencies { From 80441bdb240bd095e27ca30d6f1b387b1cf7da80 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 15:21:26 -0400 Subject: [PATCH 11/17] Apply suggestions from code review --- .../data/aws-appsync-apollo-extensions/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index cbe0c481ddc..ebddbb7b178 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -48,7 +48,7 @@ The Amplify library provides components to facilitate configuring the authorizer ### Install the AWS AppSync Apollo library -Add AWS AppSync Apollo Extensions dependency to your app/build.gradle.kts file: +Add `apollo-appsync` dependency to your app/build.gradle.kts file: ```kotlin title="app/build.gradle.kts" dependencies { From c53427f22fcc9970df89759119147dda9901e8cb Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 15:23:24 -0400 Subject: [PATCH 12/17] Update src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx --- .../data/aws-appsync-apollo-extensions/index.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index ebddbb7b178..85cf2f55512 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -227,7 +227,11 @@ dependencies { ``` ```kotlin -Code Sample +// Use CUP auth mode, reading configuration from AmplifyOutputs +val connector = ApolloAmplifyConnector(context, AmplifyOutputs(R.raw.amplify_outputs)) +val apolloClient = ApolloClient.Builder() + .appSync(connector.endpoint, connector.apiKeyAuthorizer()) + .build() ``` From f00d9ae79f368c238486158e14df844a716cc0c5 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Wed, 4 Sep 2024 15:23:44 -0400 Subject: [PATCH 13/17] Update src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx --- .../data/aws-appsync-apollo-extensions/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index 85cf2f55512..f2d64a8e8a2 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -227,7 +227,7 @@ dependencies { ``` ```kotlin -// Use CUP auth mode, reading configuration from AmplifyOutputs +// Use apiKey auth mode, reading configuration from AmplifyOutputs val connector = ApolloAmplifyConnector(context, AmplifyOutputs(R.raw.amplify_outputs)) val apolloClient = ApolloClient.Builder() .appSync(connector.endpoint, connector.apiKeyAuthorizer()) From 209e397227e3bbd2e7226654e663f5e1805e5343 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Fri, 6 Sep 2024 10:43:20 -0400 Subject: [PATCH 14/17] fix: header --- .../data/aws-appsync-apollo-extensions/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index f2d64a8e8a2..2b0a30dd788 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -38,7 +38,7 @@ To learn more about Apollo, see https://www.apollographql.com/docs/kotlin. -### Features +## Features AWS AppSync Apollo Extensions provide AWS AppSync authorizers to be used with the Apollo client to make it simple to configure runtime interceptors and apply the correct authorization payloads to your GraphQL operations. From 68c8632690dce6cfa997ac77fd0ad6db9961b041 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Fri, 6 Sep 2024 14:03:41 -0400 Subject: [PATCH 15/17] fix: links --- .../data/aws-appsync-apollo-extensions/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index 2b0a30dd788..74c50ebba2f 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -173,7 +173,7 @@ val authorizer = IamAuthorizer { ApolloAmplifyConnector.signAppSyncRequest(it, " ### Connecting Amplify Data to Apollo client -Before you begin, you will need an Amplify Data backend deploy. To get started, see [Set up Data](/[platform]/swift/build-a-backend/data/set-up-data/). +Before you begin, you will need an Amplify Data backend deploy. To get started, see [Set up Data](/[platform]/build-a-backend/data/set-up-data/). Once you have deployed your backend and created the `amplify_outputs.json` file, you can use Amplify library to read and retrieve your configuration values with the following steps: From 0ccaeac998103449c709bb67d129555f580fbd62 Mon Sep 17 00:00:00 2001 From: Matt Creaser Date: Mon, 9 Sep 2024 13:11:18 -0300 Subject: [PATCH 16/17] Improve Android Apollo Extensions documentation --- .../aws-appsync-apollo-extensions/index.mdx | 92 ++++++++++++++++--- 1 file changed, 79 insertions(+), 13 deletions(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index 74c50ebba2f..7c2c3af12ae 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -23,7 +23,7 @@ export function getStaticProps(context) { }; } -AWS AppSync Apollo Extensions provides a seamless way to connect to your AWS AppSync while using the Apollo client. Apollo client is an open-source GraphQL client. +AWS AppSync Apollo Extensions provide a seamless way to connect to your AWS AppSync backend using Apollo client, an open-source GraphQL client. @@ -40,21 +40,28 @@ To learn more about Apollo, see https://www.apollographql.com/docs/kotlin. ## Features -AWS AppSync Apollo Extensions provide AWS AppSync authorizers to be used with the Apollo client to make it simple to configure runtime interceptors and apply the correct authorization payloads to your GraphQL operations. +AWS AppSync Apollo Extensions provide AWS AppSync authorizers to be used with the Apollo client to make it simple to apply the correct authorization payloads to your GraphQL operations. The Amplify library provides components to facilitate configuring the authorizers with Apollo client by providing configuration values to connect to your Amplify Data backend. - +### Install the AWS AppSync Apollo Extensions library -### Install the AWS AppSync Apollo library + -Add `apollo-appsync` dependency to your app/build.gradle.kts file: +To connect Apollo to AppSync without using Amplify, add the `apollo-appsync` dependency to your app/build.gradle.kts file. If your +application is using Amplify Android, add the `apollo-appsync-amplify` dependency instead. ```kotlin title="app/build.gradle.kts" dependencies { // highlight-start + // Connect Apollo to AppSync without using Amplify implementation("com.amplifyframework:apollo-appsync:1.0.0") // highlight-end + // or + // highlight-start + // Connect Apollo to AppSync, delegating some implementation details to Amplify + implementation("com.amplifyframework:apollo-appsync-amplify:1.0.0") + // highlight-end } ``` @@ -62,8 +69,6 @@ dependencies { -### Install the AWS AppSync Apollo library - Add AWS AppSync Apollo Extensions into your project using Swift Package Manager. Enter its GitHub URL (`https://github.com/aws-amplify/aws-appsync-apollo-extensions-swift`), select **Up to Next Major Version** and click **Add Package** @@ -75,7 +80,7 @@ Enter its GitHub URL (`https://github.com/aws-amplify/aws-appsync-apollo-extensi ### Connecting to AWS AppSync with Apollo client -AWS AppSync supports the following [authorization modes](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html) +AWS AppSync supports the following [authorization modes](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html): #### API_KEY @@ -92,9 +97,25 @@ let interceptor = AppSyncInterceptor(authorizer) +An `ApiKeyAuthorizer` can be used with a hardcoded API key, by fetching the key from some source, or reading it from `amplify_outputs.json`: + ```kotlin +// highlight-start +// Use a hard-coded API key val authorizer = ApiKeyAuthorizer("[API_KEY]") -val interceptor = AppSyncInterceptor(authorizer) +//highlight-end +// or +// highlight-start +// Fetch the API key from some source. This function may be called many times, +// so it should implement appropriate caching internally. +val authorizer = ApiKeyAuthorizer { fetchApiKey() } +//highlight-end +// or +// highlight-start +// Using ApolloAmplifyConnector to read API key from amplify_outputs.json +val connector = ApolloAmplifyConnector(context, AmplifyOutputs(R.raw.amplify_outputs)) +val authorizer = connector.apiKeyAuthorizer() +//highlight-end ``` @@ -134,10 +155,30 @@ let interceptor = AppSyncInterceptor(authorizer) -Create the AuthTokenAuthorizer with this method. +You can use `AmplifyApolloConnector` to get an `AuthTokenAuthorizer` instance that supplies the token for the current logged-in Amplify user, or implement the token fetching yourself. ```kotlin -val authorizer = AuthTokenAuthorizer { ApolloAmplifyConnector.fetchLatestCognitoAuthToken() } +// highlight-start +// Using ApolloAmplifyConnector to get the authorizer that connects to your +// Amplify instance +val connector = ApolloAmplifyConnector(context, AmplifyOutputs(R.raw.amplify_outputs)) +val authorizer = connector.authTokenAuthorizer() +//highlight-end +// or +// highlight-start +// Using the ApolloAmplifyConnector companion function +val authorizer = AuthTokenAuthorizer { + ApolloAmplifyConnector.fetchLatestCognitoAuthToken() +} +//highlight-end +// or +// highlight-start +// Use your own token fetching. This function may be called many times, +// so it should implement appropriate caching internally. +val authorizer = AuthTokenAuthorizer { + fetchLatestAuthToken() +} +//highlight-end ``` @@ -163,10 +204,23 @@ let authorizer = IAMAuthorizer( -If you are using Amplify Auth, you can use the following method for AWS_IAM auth +If you are using `apollo-appsync-amplify`, you can use the `ApolloAmplifyConnector` to delegate token fetching and request +signing to Amplify. ```kotlin -val authorizer = IamAuthorizer { ApolloAmplifyConnector.signAppSyncRequest(it, "us-east-1") } +// highlight-start +// Using ApolloAmplifyConnector to get the authorizer that connects to your +// Amplify instance +val connector = ApolloAmplifyConnector(context, AmplifyOutputs(R.raw.amplify_outputs)) +val authorizer = connector.iamAuthorizer() +//highlight-end +// or +// highlight-start +// Using the ApolloAmplifyConnector companion function +val authorizer = IamAuthorizer { + ApolloAmplifyConnector.signAppSyncRequest(it, "us-east-1") +} +//highlight-end ``` @@ -313,6 +367,8 @@ func createApolloClient() throws -> ApolloClient { +When using `apollo-appsync`, you create `AppSyncEndpoint` and `AppSyncAuthorizer` instances, and pass them to the ApolloClient's Builder extension function. + ```kotlin val endpoint = AppSyncEndpoint("") val authorizer = /* your Authorizer */ @@ -322,4 +378,14 @@ val apolloClient = ApolloClient.Builder() .build() ``` +When using `apollo-appsync-amplify`, you can get the endpoint and authorizer from an `ApolloAmplifyConnector` to connect to your Amplify backend. + +```kotlin +val connector = ApolloAmplifyConnector(context, AmplifyOutputs(R.raw.amplify_outputs)) + +val apolloClient = ApolloClient.Builder() + .appSync(connector.endpoint, connector.apiKeyAuthorizer()) // or .authTokenAuthorizer(), or .iamAuthorizer() + .build() +``` + From 3b37722f242e3f27c1d31057900162f5ca096c53 Mon Sep 17 00:00:00 2001 From: Michael Law <1365977+lawmicha@users.noreply.github.com> Date: Thu, 19 Sep 2024 10:55:09 -0400 Subject: [PATCH 17/17] fx: add query mutation subscription section --- .../data/aws-appsync-apollo-extensions/index.mdx | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx index 7c2c3af12ae..b7068f5ad97 100644 --- a/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx @@ -309,7 +309,7 @@ The schema is used by Apollo’s code generation tool to generate API code that 1. Navigate to your API on the [AWS AppSync console](https://console.aws.amazon.com/appsync/home) 2. On the left side, select Schema 3. When viewing your schema, there should a “Export schema” drop down. Select this and download the `schema.json` file. -4. Add this file to your project as directed by [Apollo Code Generation documentation](https://www.apollographql.com/docs/ios/code-generation/introduction) +4. Add this file to your project as directed by [Apollo Code Generation documentation](https://www.apollographql.com/docs/ios/code-generation/introduction). You can alternatively download the introspection schema using the [`fetch-schema`](https://www.apollographql.com/docs/ios/code-generation/codegen-cli#fetch-schema) command with the `amplify-ios-cli` tool. @@ -322,6 +322,13 @@ You can alternatively download the introspection schema using the [`fetch-schema 4. Add this file to your project as directed by [Apollo documentation](https://www.apollographql.com/docs/kotlin/advanced/plugin-recipes#specifying-the-schema-location) +### Performing Queries, Mutations, and Subscriptions with Apollo client + +1. Navigate to the **Queries** tab in your API on the [AWS AppSync console](https://console.aws.amazon.com/appsync/home). Here, you can test queries, mutations, and subscriptions in the GraphQL playground. +2. Enter your GraphQL operation (query, mutation, or subscription) in the editor and click **Run** to execute it. +3. Observe the request and response structure in the results. This gives you insight into the exact call patterns and structure that Apollo will use. +4. Copy the GraphQL operation from the playground and pass it to Apollo's code generation tool to automatically generate the corresponding API code for your project. + ## Connecting to AWS AppSync real-time endpoint The following example shows how you can create an Apollo client that allows performing GraphQL subscription operations with AWS AppSync.