From 833925cd1bd0e8ed8c2fa69ef60ccb29543c5221 Mon Sep 17 00:00:00 2001 From: tjroach Date: Thu, 23 Jan 2025 15:53:40 -0500 Subject: [PATCH 1/8] Improve Android AppSync Extensions documentation --- .../aws-appsync-apollo-extensions/index.mdx | 368 +++++++++++------- 1 file changed, 218 insertions(+), 150 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 53327933062..ad0cf95e16b 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,8 +23,7 @@ export function getStaticProps(context) { }; } -AWS AppSync Apollo Extensions provide a seamless way to connect to your AWS AppSync backend using Apollo client, 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. The included AWS AppSync authorizers make it simple to apply the correct authorization payloads to your GraphQL operations within the Apollo client. The library allows you to connect directly to your AWS AppSync backend, including AppSync backends managed through Amplify Data. To learn more about Apollo, see https://www.apollographql.com/docs/ios/. @@ -38,18 +37,30 @@ To learn more about Apollo, see https://www.apollographql.com/docs/kotlin. -## Features +## Install the AWS AppSync Apollo Extensions library -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 + - +Add the `apollo-appsync-amplify` 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, delegating some implementation details to Amplify + implementation("com.amplifyframework:apollo-appsync-amplify:1.0.0") + // highlight-end +} +``` + + + + + +Add the `apollo-appsync` dependency to your app/build.gradle.kts file. ```kotlin title="app/build.gradle.kts" dependencies { @@ -57,13 +68,11 @@ dependencies { // 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 } ``` + + + @@ -78,29 +87,49 @@ Enter its GitHub URL (`https://github.com/aws-amplify/aws-appsync-apollo-extensi -### Connecting to AWS AppSync with Apollo client +## 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 + - + +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/). -```swift -import AWSAppSyncApolloExtensions +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: -let authorizer = APIKeyAuthorizer(apiKey: "[API_KEY]") -let interceptor = AppSyncInterceptor(authorizer) +```kotlin +// 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()) + .build() ``` - +### AppSync Authorizers - +Depending on the 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** -An `ApiKeyAuthorizer` can be used with a hardcoded API key, by fetching the key from some source, or reading it from `amplify_outputs.json`: +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. + +#### API_KEY + +An `ApiKeyAuthorizer` can be read from `amplify_outputs.json`, provided with a hardcoded API key or by fetching the key from some source: ```kotlin // 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 +// or +// highlight-start // Use a hard-coded API key val authorizer = ApiKeyAuthorizer("[API_KEY]") //highlight-end @@ -110,51 +139,10 @@ val authorizer = ApiKeyAuthorizer("[API_KEY]") // 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 ``` - - #### 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) -``` - - - - 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 @@ -181,30 +169,11 @@ val authorizer = AuthTokenAuthorizer { //highlight-end ``` - - 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 - -```swift -import AWSCognitoAuthPlugin -import AWSAppSyncApolloExtensions - -let authorizer = IAMAuthorizer( - signRequest: AWSCognitoAuthPlugin.createAppSyncSigner( - region: "[REGION]")) -``` - - - - - -If you are using `apollo-appsync-amplify`, you can use the `ApolloAmplifyConnector` to delegate token fetching and request +You can use the `ApolloAmplifyConnector` to delegate token fetching and request signing to Amplify. ```kotlin @@ -223,15 +192,123 @@ val authorizer = IamAuthorizer { //highlight-end ``` + + + + +```kotlin +val endpoint = AppSyncEndpoint("") +// Continue Reading to see more authorizer examples +val authorizer = ApiKeyAuthorizer("[API_KEY]") + +val apolloClient = ApolloClient.Builder() + .appSync(endpoint, authorizer) + .build() +``` + +### AppSync Authorizers + +AWS AppSync supports the following [authorization modes](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html): + +#### API_KEY + +An `ApiKeyAuthorizer` can be used with a hardcoded API key or by fetching the key from some source.: + +```kotlin +// highlight-start +// Use a hard-coded API key +val authorizer = ApiKeyAuthorizer("[API_KEY]") +//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 +``` + +#### AMAZON_COGNITO_USER_POOLS + +When working directly with AppSync, you must implement the token fetching yourself. + +```kotlin +// 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 +``` + + + + -### 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]/build-a-backend/data/set-up-data/). + +AWS AppSync supports the following [authorization modes](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html): -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: +### API_KEY + +```swift +import AWSAppSyncApolloExtensions + +let authorizer = APIKeyAuthorizer(apiKey: "[API_KEY]") +let 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) +``` + +### AWS_IAM + +If you are using Amplify Auth, you can use the following method for AWS_IAM auth + +```swift +import AWSCognitoAuthPlugin +import AWSAppSyncApolloExtensions + +let authorizer = IAMAuthorizer( + signRequest: AWSCognitoAuthPlugin.createAppSyncSigner( + region: "[REGION]")) +``` + +## 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]/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: 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: @@ -266,32 +343,7 @@ func createApolloClient() throws -> ApolloClient { } ``` - - - - -Add `apollo-appsync-amplify` dependency to your app/build.gradle.kts file: - -```kotlin title="app/build.gradle.kts" -dependencies { - // highlight-start - implementation("com.amplifyframework:apollo-appsync-amplify:1.0.0") - // highlight-end -} -``` - -```kotlin -// 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()) - .build() -``` - - - -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). - +Depending on the 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 @@ -301,7 +353,9 @@ Some common ones are 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 + + +## 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. The following steps integrate your AppSync schema with Apollo's code generation process: @@ -316,12 +370,58 @@ You can alternatively download the introspection schema using the [`fetch-schema + 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 documentation](https://www.apollographql.com/docs/kotlin/advanced/plugin-recipes#specifying-the-schema-location) -### Type Mapping AppSync Scalars + + +## Generating Queries, Mutations, and Subscriptions for Apollo client + + + + + + +### Amplify provided .graphql files +1. Within your Amplify Gen2 backend, run: `npx ampx generate graphql-client-code --format graphql-codegen --statement-target graphql --out graphql` +2. Copy the generated files (`mutations.graphql`, `queries.graphql`, `subscriptions.graphql`) to your `{app}/src/main/graphql` folder as shown in the [Apollo documentation](https://www.apollographql.com/docs/kotlin#getting-started) + +### Manual +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(s) from the playground and pass them to to your `{app}/src/main/graphql` folder as shown in the [Apollo documentation](https://www.apollographql.com/docs/kotlin#getting-started) + + + + + +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. + + + + + + + + + +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. + + + + + +## Type Mapping AppSync Scalars By default, [AWS AppSync Scalars](https://docs.aws.amazon.com/appsync/latest/devguide/scalars.html#graph-ql-aws-appsync-scalars) will default to the `Any` type. You can map these scalars to more explicit types by editing the `apollo` block in your `app/build.gradle[.kts]` file. In the example below, we are now mapping a few of our AppSync scalar types to `String` instead of `Any`. Additional improvements could be made by writing [custom class adapters](https://www.apollographql.com/docs/kotlin/essentials/custom-scalars#define-class-mapping) to convert date/time scalars into Kotlin date/time class types. ```kotlin @@ -335,19 +435,12 @@ apollo { ``` -### 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. - - ```swift import Apollo import ApolloAPI @@ -384,28 +477,3 @@ 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 */ - -val apolloClient = ApolloClient.Builder() - .appSync(endpoint, authorizer) - .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 43fc644013c64ec491aa54f14d55a8e6ec70eff6 Mon Sep 17 00:00:00 2001 From: tjroach Date: Fri, 24 Jan 2025 10:35:08 -0500 Subject: [PATCH 2/8] updates --- .../aws-appsync-apollo-extensions/index.mdx | 26 ++++++++++++++++--- 1 file changed, 23 insertions(+), 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 ad0cf95e16b..167291a0cd5 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 @@ -116,7 +116,7 @@ Some common ones are * `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. +If you define multiple authorization strategies within your schema, you will have to create separate Apollo client instances for each Authorizer that you want to use in your app. #### API_KEY @@ -208,7 +208,15 @@ val apolloClient = ApolloClient.Builder() ### AppSync Authorizers -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). Use the corresponding Authorizer that matches the chosen authorization type. + +Some common ones are + +* API Key Authorization -> **APIKeyAuthorizer** +* IAM Authorization -> **IAMAuthorizer** +* Cognito User Pools -> **AuthTokenAuthorizer** + +If you apply multiple authorization directives in your schema, you will have to create separate Apollo client instances for each Authorizer that you want to use in your app. #### API_KEY @@ -240,6 +248,18 @@ val authorizer = AuthTokenAuthorizer { } //highlight-end ``` + +#### AWS_IAM + +When working directly with AppSync, you must implement the request signing yourself. + +```kotlin +// highlight-start +// Provide an implementation of the signing function. This function should implement the +// AWS Sig-v4 signing logic and return the authorization headers containing the token and signature. +val authorizer = IamAuthorizer { signRequestAndReturnHeaders(it) } +// highlight-end +``` @@ -351,7 +371,7 @@ Some common ones are * `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. +If you define multiple authorization strategies within your schema, you will have to create separate Apollo client instances for each Authorizer that you want to use in your app. From 26d73331683fad975f783c2cf35526029e18e5b1 Mon Sep 17 00:00:00 2001 From: Tyler Roach Date: Fri, 24 Jan 2025 14:28:58 -0500 Subject: [PATCH 3/8] Update src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx Co-authored-by: Matt Creaser --- .../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 167291a0cd5..ac057bac6a7 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 @@ -120,7 +120,7 @@ If you define multiple authorization strategies within your schema, you will hav #### API_KEY -An `ApiKeyAuthorizer` can be read from `amplify_outputs.json`, provided with a hardcoded API key or by fetching the key from some source: +An `ApiKeyAuthorizer` can read the API key from `amplify_outputs.json`, provide a hardcoded API key, or fetch the API key from some source: ```kotlin // highlight-start From 4263abe5d441efaa496b385ee05ad016472b97a9 Mon Sep 17 00:00:00 2001 From: tjroach Date: Fri, 24 Jan 2025 15:07:58 -0500 Subject: [PATCH 4/8] updates --- .../aws-appsync-apollo-extensions/index.mdx | 37 +++++++++++++------ 1 file changed, 25 insertions(+), 12 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 ac057bac6a7..132abf0e2ae 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,27 +23,38 @@ export function getStaticProps(context) { }; } -AWS AppSync Apollo Extensions provide a seamless way to connect to your AWS AppSync backend using Apollo client, an open-source GraphQL client. The included AWS AppSync authorizers make it simple to apply the correct authorization payloads to your GraphQL operations within the Apollo client. The library allows you to connect directly to your AWS AppSync backend, including AppSync backends managed through Amplify Data. +AWS AppSync Apollo Extensions provide a seamless way to connect to your AWS AppSync backend using Apollo client, 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 apply the correct authorization payloads to your GraphQL operations. + + +Additionally, we publish an optional Amplify extension that allows Amplify to provide auth tokens and signing logic for the corresponding Authorizers. + + + +Additionally, the included Amplify components allow Amplify to provide auth tokens and signing logic for the corresponding Authorizers. + + ## Install the AWS AppSync Apollo Extensions library - + Add the `apollo-appsync-amplify` dependency to your app/build.gradle.kts file. @@ -58,7 +69,7 @@ dependencies { - + Add the `apollo-appsync` dependency to your app/build.gradle.kts file. @@ -93,7 +104,7 @@ Enter its GitHub URL (`https://github.com/aws-amplify/aws-appsync-apollo-extensi - + 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: @@ -108,7 +119,7 @@ val apolloClient = ApolloClient.Builder() ### AppSync Authorizers -Depending on the 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). +The AWS AppSync Apollo Extensions library provides a number of Authorizer classes to match the various authorization strategies that may be in use in your schema. You should choose the appropriate Authorizer type for your authorization strategy. 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 @@ -194,7 +205,9 @@ val authorizer = IamAuthorizer { - + + +You can create your Apollo client by using our provided AWS AppSync endpoint and authorizer classes. ```kotlin val endpoint = AppSyncEndpoint("") @@ -363,7 +376,7 @@ func createApolloClient() throws -> ApolloClient { } ``` -Depending on the 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). +The AWS AppSync Apollo Extensions library provides a number of Authorizer classes to match the various authorization strategies that may be in use in your schema. You should choose the appropriate Authorizer type for your authorization strategy. 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 @@ -382,7 +395,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. +3. Select the "Export schema" dropdown 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. @@ -393,7 +406,7 @@ You can alternatively download the introspection schema using the [`fetch-schema 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. +3. Select the "Export schema" dropdown and download the `schema.json` file. 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) @@ -404,7 +417,7 @@ You can alternatively download the introspection schema using the [`fetch-schema - + ### Amplify provided .graphql files 1. Within your Amplify Gen2 backend, run: `npx ampx generate graphql-client-code --format graphql-codegen --statement-target graphql --out graphql` 2. Copy the generated files (`mutations.graphql`, `queries.graphql`, `subscriptions.graphql`) to your `{app}/src/main/graphql` folder as shown in the [Apollo documentation](https://www.apollographql.com/docs/kotlin#getting-started) @@ -417,7 +430,7 @@ You can alternatively download the introspection schema using the [`fetch-schema - + 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. From 7c9249fded3949b807c1cb4ee3a17c8b95e3d66e Mon Sep 17 00:00:00 2001 From: Tyler Roach Date: Mon, 27 Jan 2025 08:19:45 -0500 Subject: [PATCH 5/8] Update src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx Co-authored-by: josef --- .../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 132abf0e2ae..9ad43c487ec 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 @@ -424,7 +424,7 @@ You can alternatively download the introspection schema using the [`fetch-schema ### Manual 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. +2. Enter your GraphQL operation (query, mutation, or subscription) in the editor and select **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(s) from the playground and pass them to to your `{app}/src/main/graphql` folder as shown in the [Apollo documentation](https://www.apollographql.com/docs/kotlin#getting-started) From 8b4c806b60764ecf2ceff306fd2f805646cf6e42 Mon Sep 17 00:00:00 2001 From: tjroach Date: Tue, 28 Jan 2025 09:21:43 -0500 Subject: [PATCH 6/8] PR comments --- .../aws-appsync-apollo-extensions/index.mdx | 48 +++++++++++-------- 1 file changed, 28 insertions(+), 20 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 132abf0e2ae..a14d9224906 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 @@ -102,6 +102,8 @@ Enter its GitHub URL (`https://github.com/aws-amplify/aws-appsync-apollo-extensi +### Creating the ApolloClient + @@ -116,8 +118,28 @@ val apolloClient = ApolloClient.Builder() .appSync(connector.endpoint, connector.apiKeyAuthorizer()) .build() ``` + + + +You can create your Apollo client by using our provided AWS AppSync endpoint and authorizer classes. -### AppSync Authorizers +```kotlin +val endpoint = AppSyncEndpoint("") +// Continue Reading to see more authorizer examples +val authorizer = ApiKeyAuthorizer("[API_KEY]") +val apolloClient = ApolloClient.Builder() + .appSync(endpoint, authorizer) + .build() +``` + + + + +### Providing AppSync Authorizers + + + + The AWS AppSync Apollo Extensions library provides a number of Authorizer classes to match the various authorization strategies that may be in use in your schema. You should choose the appropriate Authorizer type for your authorization strategy. 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). @@ -207,20 +229,6 @@ val authorizer = IamAuthorizer { -You can create your Apollo client by using our provided AWS AppSync endpoint and authorizer classes. - -```kotlin -val endpoint = AppSyncEndpoint("") -// Continue Reading to see more authorizer examples -val authorizer = ApiKeyAuthorizer("[API_KEY]") - -val apolloClient = ApolloClient.Builder() - .appSync(endpoint, authorizer) - .build() -``` - -### AppSync Authorizers - AWS AppSync supports the following [authorization modes](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html). Use the corresponding Authorizer that matches the chosen authorization type. Some common ones are @@ -283,7 +291,7 @@ val authorizer = IamAuthorizer { signRequestAndReturnHeaders(it) } AWS AppSync supports the following [authorization modes](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html): -### API_KEY +#### API_KEY ```swift import AWSAppSyncApolloExtensions @@ -292,7 +300,7 @@ let authorizer = APIKeyAuthorizer(apiKey: "[API_KEY]") let interceptor = AppSyncInterceptor(authorizer) ``` -### AMAZON_COGNITO_USER_POOLS +#### AMAZON_COGNITO_USER_POOLS If you are using Amplify Auth, you can create a method that retrieves the Cognito access token @@ -322,7 +330,7 @@ let authorizer = AuthTokenAuthorizer(fetchLatestAuthToken: getUserPoolAccessToke let interceptor = AppSyncInterceptor(authorizer) ``` -### AWS_IAM +#### AWS_IAM If you are using Amplify Auth, you can use the following method for AWS_IAM auth @@ -418,11 +426,11 @@ You can alternatively download the introspection schema using the [`fetch-schema -### Amplify provided .graphql files +#### Amplify provided .graphql files 1. Within your Amplify Gen2 backend, run: `npx ampx generate graphql-client-code --format graphql-codegen --statement-target graphql --out graphql` 2. Copy the generated files (`mutations.graphql`, `queries.graphql`, `subscriptions.graphql`) to your `{app}/src/main/graphql` folder as shown in the [Apollo documentation](https://www.apollographql.com/docs/kotlin#getting-started) -### Manual +#### Manual 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. From e6f1bfec1c015aa6d3e27c1f3d79ca7ab97d282a Mon Sep 17 00:00:00 2001 From: tjroach Date: Tue, 28 Jan 2025 16:36:52 -0500 Subject: [PATCH 7/8] formatting --- .../data/aws-appsync-apollo-extensions/index.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 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 9b1a266913a..6d4f1abe0ca 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 @@ -291,7 +291,7 @@ val authorizer = IamAuthorizer { signRequestAndReturnHeaders(it) } AWS AppSync supports the following [authorization modes](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html): -#### API_KEY +### API_KEY ```swift import AWSAppSyncApolloExtensions @@ -300,7 +300,7 @@ let authorizer = APIKeyAuthorizer(apiKey: "[API_KEY]") let interceptor = AppSyncInterceptor(authorizer) ``` -#### AMAZON_COGNITO_USER_POOLS +### AMAZON_COGNITO_USER_POOLS If you are using Amplify Auth, you can create a method that retrieves the Cognito access token @@ -330,7 +330,7 @@ let authorizer = AuthTokenAuthorizer(fetchLatestAuthToken: getUserPoolAccessToke let interceptor = AppSyncInterceptor(authorizer) ``` -#### AWS_IAM +### AWS_IAM If you are using Amplify Auth, you can use the following method for AWS_IAM auth @@ -426,11 +426,11 @@ You can alternatively download the introspection schema using the [`fetch-schema -#### Amplify provided .graphql files +**Amplify provided .graphql files** 1. Within your Amplify Gen2 backend, run: `npx ampx generate graphql-client-code --format graphql-codegen --statement-target graphql --out graphql` 2. Copy the generated files (`mutations.graphql`, `queries.graphql`, `subscriptions.graphql`) to your `{app}/src/main/graphql` folder as shown in the [Apollo documentation](https://www.apollographql.com/docs/kotlin#getting-started) -#### Manual +**Manual** 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 select **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. From fbe8e8c591665535e9f95683a94c3294c6c04eec Mon Sep 17 00:00:00 2001 From: Tyler Roach Date: Tue, 28 Jan 2025 19:30:11 -0500 Subject: [PATCH 8/8] Update src/pages/[platform]/build-a-backend/data/aws-appsync-apollo-extensions/index.mdx Co-authored-by: josef --- .../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 6d4f1abe0ca..d12f1f7d0a5 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 @@ -427,7 +427,7 @@ You can alternatively download the introspection schema using the [`fetch-schema **Amplify provided .graphql files** -1. Within your Amplify Gen2 backend, run: `npx ampx generate graphql-client-code --format graphql-codegen --statement-target graphql --out graphql` +1. Within your Amplify Gen 2 backend, run: `npx ampx generate graphql-client-code --format graphql-codegen --statement-target graphql --out graphql` 2. Copy the generated files (`mutations.graphql`, `queries.graphql`, `subscriptions.graphql`) to your `{app}/src/main/graphql` folder as shown in the [Apollo documentation](https://www.apollographql.com/docs/kotlin#getting-started) **Manual**