Calling AppSync GraphQL from Lambda

AWS AppSync provides an easy way to run a GraphQL API that triggers AWS Lambda functions and other AWS services. If you start with AppSync, you likely have existing systems running next to it. Sooner or later, you want to call the GraphQL API from your Lambda function (Node.js). For example, to trigger an AppSync subscription from another system.

To do so, you need:

1. A GraphQL client library
2. Authentication
3. Send your GraphQL request to the AppSync endpoint

Let’s walk through the steps.

Installing the library dependencies

The easiest way to talk to an AppSync GraphQL API is by using the aws-appsync package which wraps the apollo GraphQL client package. The libraries assume that they run in a browser environment where the Fetch API is available. The package cross-fetch provides a polyfill to bring The Fetch API to Node.js environments as well. The package graphql-tag is used to parse a GraphQL query.

npm i aws-appsync@1.8.1
npm i cross-fetch@3.0.4
npm i graphql-tag@2.10.1

Creating a client with authentication

AppSync supports multiple authentication types. If your API uses AWS_IAM, you are all fine. If not:

1. In your AppSync Api Settings, go to Additional auth providers and add AWS_IAM
2. Add the schema directive @aws_iam to the mutation like this

type Mutation {
  # used internally to trigger the subscription
  test(value: String!): String
  @aws_iam
}

In your JavaScript code, create a client object:

const appsync = require('aws-appsync');
const gql = require('graphql-tag');
require('cross-fetch/polyfill');

const graphqlClient = new appsync.AWSAppSyncClient({
  url: 'APPSYNC_ENDPOINT_URL',
  region: process.env.AWS_REGION,
  auth: {
    type: 'AWS_IAM',
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
      sessionToken: process.env.AWS_SESSION_TOKEN
    }
  },
  disableOffline: true
});

Now, you are ready to send your GraphQL request to the AppSync endpoint

Sending your GraphQL request to the AppSync endpoint

Finally, you create your GraphQL query and send it to the endpoint.

const mutation = gql`mutation Test($value: String!) {
  test(value: $value)
}`;
await graphqlClient.mutate({
  mutation,
  variables: {
    value: 'test'
  }
});

Keep in mind that your Lambda function needs the following permission to invoke the AppSync API endpoint (replace REGION with the region identifier and AWS_ACCOUNT_ID with the AWS account id):

{
  "Effect": "Allow",
  "Action": "appsync:GraphQL",
  "Resource": "arn:aws:appsync:REGION:ACCOUNT_ID:apis/API_ID/types/Mutation/fields/test"
}

Summary

Invoking a AppSync GraphQL API endpoint from Lambda requires a few tricks. A typical use case for calling an AppSync API from a Lambda function is to trigger a subscription from an external system.