From 0ccaeac998103449c709bb67d129555f580fbd62 Mon Sep 17 00:00:00 2001 From: Matt Creaser Date: Mon, 9 Sep 2024 13:11:18 -0300 Subject: [PATCH] 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() +``` +