AWS AppSync Apollo Extensions

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/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.

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

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.

dependencies {
Copy highlighted code example
    // Connect Apollo to AppSync without using Amplify
    implementation("com.amplifyframework:apollo-appsync:1.0.0")    
    // or
Copy highlighted code example
    // Connect Apollo to AppSync, delegating some implementation details to Amplify
    implementation("com.amplifyframework:apollo-appsync-amplify:1.0.0")    
}

Connecting to AWS AppSync with Apollo client

AWS AppSync supports the following authorization modes:

API_KEY

An ApiKeyAuthorizer can be used with a hardcoded API key, by fetching the key from some source, or reading it from amplify_outputs.json:

Copy highlighted code example
// Use a hard-coded API key
val authorizer = ApiKeyAuthorizer("[API_KEY]")
// or
Copy highlighted code example
// 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() }
// or
Copy highlighted code example
// Using ApolloAmplifyConnector to read API key from amplify_outputs.json
val connector = ApolloAmplifyConnector(context, AmplifyOutputs(R.raw.amplify_outputs))
val authorizer = connector.apiKeyAuthorizer()

AMAZON_COGNITO_USER_POOLS

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.

Copy highlighted code example
// 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()
// or
Copy highlighted code example
// Using the ApolloAmplifyConnector companion function
val authorizer = AuthTokenAuthorizer { 
  ApolloAmplifyConnector.fetchLatestCognitoAuthToken() 
}
// or
Copy highlighted code example
// Use your own token fetching. This function may be called many times,
// so it should implement appropriate caching internally.
val authorizer = AuthTokenAuthorizer {
  fetchLatestAuthToken()
}

You can provide your own custom fetchLatestAuthToken provider for AWS_LAMBDA and OPENID_CONNECT auth modes.

AWS_IAM

If you are using apollo-appsync-amplify, you can use the ApolloAmplifyConnector to delegate token fetching and request signing to Amplify.

Copy highlighted code example
// 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()
// or
Copy highlighted code example
// Using the ApolloAmplifyConnector companion function
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.

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:

Add apollo-appsync-amplify dependency to your app/build.gradle.kts file:

dependencies {
Copy highlighted code example
    implementation("com.amplifyframework:apollo-appsync-amplify:1.0.0")    
}

// 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.

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. The following steps integrate your AppSync schema with Apollo's code generation process:

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 documentation

Performing Queries, Mutations, and Subscriptions with Apollo client

1. Navigate to the Queries tab in your API on the AWS AppSync console. 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.

When using apollo-appsync, you create AppSyncEndpoint and AppSyncAuthorizer instances, and pass them to the ApolloClient's Builder extension function.

val endpoint = AppSyncEndpoint("<your_appsync_endpoint>")
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.

val connector = ApolloAmplifyConnector(context, AmplifyOutputs(R.raw.amplify_outputs))

val apolloClient = ApolloClient.Builder()
    .appSync(connector.endpoint, connector.apiKeyAuthorizer()) // or .authTokenAuthorizer(), or .iamAuthorizer()
    .build()