Front-End Web & Mobile

Building Scalable GraphQL APIs on AWS with CDK, TypeScript, AWS AppSync, Amazon DynamoDB, and AWS Lambda

AWS AppSync is a managed serverless GraphQL service that simplifies application development by letting you create a flexible API to securely access, manipulate, and combine data from one or more data sources with a single network call and API endpoint. With AppSync, developers can build scalable applications on a range of data sources, including Amazon DynamoDB NoSQL tables, Amazon Aurora Serverless relational databases, Amazon Elasticsearch clusters, HTTP APIs, and serverless functions powered by AWS Lambda.

AppSync APIs can be deployed in a variety of different ways using various CloudFormation providers like the Amplify CLI, SAM, CDK, and the Serverless Framework (among others).

In this post, we’ll be building an AWS AppSync API from scratch using CDK. The post will focus on how to use CDK to deploy AppSync APIs that leverage a variety of AWS services including Amazon DynamoDB and AWS Lambda.

The API we will be deploying will be leveraging a DynamoDB database for creating, reading, updating, and deleting data. We’ll learn how to map GraphQL requests to DynamoDB using Direct Lambda resolvers. We’ll also learn how to enable GraphQL subscriptions for real-time updates triggered from database events.

The final code for this project is located here.

CDK Overview

The AWS Cloud Development Kit (AWS CDK) is an open source software development framework to model and provision your cloud application resources using familiar programming languages. CDK can be written using a variety of programming languages like Python, Java, TypeScript, JavaScript, and C#. In this tutorial we will be using TypeScript

To work with CDK, you will need to install the CDK CLI. Once the CLI is installed, you will be able to do things like create new CDK projects, deploy services to AWS, deploy updates to existing services, and view changes made to your infrastructure during the development process.

In this post we’ll be using the CDK CLI to provision and deploy API updates.

CDK with AppSync

An AppSync API is usually composed of various AWS services. For example, if we are building an AppSync API that interacts with a database and needs authorization, the API will depend on these resources being created.

With this in mind, we will not only be working with CDK modules for AppSync but also various other AWS services. Part of building an AppSync API is learning how to use all of these things and making them work well together, including managing IAM policies in certain circumstances in order to enable access between services or to configure certain types of data access patterns.

The AppSync CDK constructs and classes take this into consideration and enable the configuration of various resources within an AppSync API using AWS services also created as part of the CDK project.

Click here to view the CDK documentation. Click here to view the AWS AppSync documentation.

Getting Started

First, install the CDK CLI:

npm install -g aws-cdk

You must also provide your credentials and an AWS Region to use AWS CDK, if you have not already done so. The easiest way to satisfy this requirement is to install the AWS CLI and issue the following command:

aws configure

Next, create a directory called appsync-cdk-app and change into the new directory:

mkdir appsync-cdk-app

cd appsync-cdk-app

Next, we’ll create a new CDK project using the CDK CLI:

cdk init --language=typescript

The CDK project should now be initialized and you should see a few files in the directory, including a lib folder which is where the boilerplate for the root stack has been created.

Now that we’ve created the CDK project, let’s install the necessary dependencies we’ll need. Since we’ll be working with several different packages, we’ll need to go ahead and install them now:

npm install @aws-cdk/aws-appsync @aws-cdk/aws-lambda @aws-cdk/aws-dynamodb

Running a build

Because the project is written in TypeScript, but will ultimately need to be deployed in JavaScript, you will need to create a build to convert the TypeScript into JavaScript before deploying.

There are two ways to do this, and the project is already set up with a couple of scripts to help with this.

Watch mode

You can run npm run watch to enable watch mode. The project will automatically compile to JS as soon as you make changes and save files and you will also be able to see any errors logged out to the terminal.

Manual build

You can also create a build at any time by running npm run build.

Creating the API

Now that the project is set up, we can start writing some code! Some boilerplate code for the stack has already been created for you. This code is located at appsync-cdk-app/lib/appsync-cdk-app-stack.ts. This is the root of the CDK app and where we will be writing the code for our app.

To get started, let’s first go ahead and import the CDK modules we’ll be needing:

// lib/appsync-cdk-app-stack.ts
import * as cdk from '@aws-cdk/core';
import * as appsync from '@aws-cdk/aws-appsync';
import * as ddb from '@aws-cdk/aws-dynamodb';
import * as lambda from '@aws-cdk/aws-lambda';

Next we’ll use the appsync CDK module to create the API. Update the Stack with following code:

// lib/appsync-cdk-app-stack.ts
export class AppsyncCdkAppStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Creates the AppSync API
    const api = new appsync.GraphqlApi(this, 'Api', {
      name: 'cdk-notes-appsync-api',
      schema: appsync.Schema.fromAsset('graphql/schema.graphql'),
      authorizationConfig: {
        defaultAuthorization: {
          authorizationType: appsync.AuthorizationType.API_KEY,
          apiKeyConfig: {
            expires: cdk.Expiration.after(cdk.Duration.days(365))
          }
        },
      },
      xrayEnabled: true,
    });

    // Prints out the AppSync GraphQL endpoint to the terminal
    new cdk.CfnOutput(this, "GraphQLAPIURL", {
     value: api.graphqlUrl
    });

    // Prints out the AppSync GraphQL API key to the terminal
    new cdk.CfnOutput(this, "GraphQLAPIKey", {
      value: api.apiKey || ''
    });

    // Prints out the stack region to the terminal
    new cdk.CfnOutput(this, "Stack Region", {
      value: this.region
    });
  }
}

We’ve defined a basic AppSync API with the following configuration:

  • name: Defines the name of the AppSync API
  • schema: Specifies the location of the GraphQL schema
  • authorizationConfig: This allows you to define the default authorization mode its configuration, as well as (optional) additional authorization modes
  • xrayEnabled: Enables xray debugging

Next, we need to define the GraphQL schema. Create a new folder in the root of the project named graphql and within it, create a new file named schema.graphql:

# graphql/schema.graphql
type Note {
  id: ID!
  name: String!
  completed: Boolean!
}

input NoteInput {
  id: ID!
  name: String!
  completed: Boolean!
}

input UpdateNoteInput {
  id: ID!
  name: String
  completed: Boolean
}

type Query {
  getNoteById(noteId: String!): Note
  listNotes: [Note]
}

type Mutation {
  createNote(note: NoteInput!): Note
  updateNote(note: UpdateNoteInput!): Note
  deleteNote(noteId: String!): String
}

This schema defines a notes app with two queries and three mutations for basic CRUD + List functionality.

Now, or any time, we can run run a build and use the CDK diff command to see what changes will be deployed:

npm run build && cdk diff

The diff command compares the current version of a stack defined in your app with the already-deployed version and displays a list of differences.

From here, we can build and deploy the API to see it in the AppSync console. To do so, run the following command from your terminal:

npm run build && cdk deploy

When the build finishes, you should see JavaScript files compiled from the TypeScript files in your project.

Once the deployment is complete, you should be able to see the API (cdk-notes-appsync-api) in the AppSync console.

🎉 Congratulations, you’ve successfully deployed an AppSync API using CDK!

Adding a Lambda Data Source

Now that we’ve created the API, we need a way to connect the GraphQL operations (createNote, updateNote, listNotes, etc..) to a data source. We will be doing this by mapping the operations into a Lambda function that will be interacting with a DynamoDB table.

To build out this functionality, we’ll next need to create the Lambda function and then add it as a data source to the AppSync API. Add the following code below the API definition in lib/appsync-cdk-app-stack.ts:

// lib/appsync-cdk-app-stack.ts
const notesLambda = new lambda.Function(this, 'AppSyncNotesHandler', {
  runtime: lambda.Runtime.NODEJS_12_X,
  handler: 'appsync-ds-main.handler',
  code: lambda.Code.fromAsset('lambda-fns'),
  memorySize: 1024
});

// Set the new Lambda function as a data source for the AppSync API
const lambdaDs = api.addLambdaDataSource('lambdaDatasource', notesLambda);

Next, create a new folder called lambda-fns in the root of your project.

Now, when you run npm run build && cdk diff you should see there is a new Lambda function that is enabled for your API.

Attaching the GraphQL resolvers

Now that the Lambda DataSource has been created, we need to enable the Resolvers for the GraphQL operations to interact with the data source. To do so, we can add the following code below the Lambda data source definition:

// lib/appsync-cdk-app-stack.ts
lambdaDs.createResolver({
  typeName: "Query",
  fieldName: "getNoteById"
});

lambdaDs.createResolver({
  typeName: "Query",
  fieldName: "listNotes"
});

lambdaDs.createResolver({
  typeName: "Mutation",
  fieldName: "createNote"
});

lambdaDs.createResolver({
  typeName: "Mutation",
  fieldName: "deleteNote"
});

lambdaDs.createResolver({
  typeName: "Mutation",
  fieldName: "updateNote"
});

Adding a DynamoDB Table

Now that the Lambda function has been configured we need to create a DynamoDB table and enable the Lambda function to access it.

To do so, we’ll add the following code below the GraphQL resolver definitions in lib/appsync-cdk-app-stack.ts:

// lib/appsync-cdk-app-stack.ts
const notesTable = new ddb.Table(this, 'CDKNotesTable', {
  billingMode: ddb.BillingMode.PAY_PER_REQUEST,
  partitionKey: {
    name: 'id',
    type: ddb.AttributeType.STRING,
  },
});
// enable the Lambda function to access the DynamoDB table (using IAM)
notesTable.grantFullAccess(notesLambda)

// Create an environment variable that we will use in the function code
notesLambda.addEnvironment('NOTES_TABLE', notesTable.tableName);

We’ve now created a DynamoDB table, enabled the Lambda function to access it by configuring IAM permissions, and created an environment variable referencing the DynamoDB table name that we will use in the Lambda function.

Adding the Lambda function code

Finally we need to add the function code that we will be using to map the GraphQL queries and mutations into DynamoDB operations.

We can use the event object that is passed into the function argument to find the fieldName of the operation that is invoking the function and then map the invocation to the proper DynamoDB operation.

For example, if the GraphQL operation that triggered the function is createNote, then the fieldName will be available at event.info.fieldName.

We can also access any arguments that are passed into the GraphQL operation by accessing the event.arguments object.

With this in mind, create the following files in the lambda-fns directory: appsync-ds-main.ts, createNote.ts, deleteNote.ts, getNoteById.ts, listNotes.ts, updateNote.ts, and Note.ts.

Next, we’ll update these files with the code needed to interact with the DynamoDB table and perform various operations.

appsync-ds-main.ts

// lambda-fns/appsync-ds-main.ts

import createNote from './createNote';
import deleteNote from './deleteNote';
import getNoteById from './getNoteById';
import listNotes from './listNotes';
import updateNote from './updateNote';
import Note = require('./Note');

type AppSyncEvent = {
   info: {
     fieldName: string
  },
   arguments: {
     noteId: string,
     note: Note
  }
}

exports.handler = async (event:AppSyncEvent) => {
    switch (event.info.fieldName) {
        case "getNoteById":
            return await getNoteById(event.arguments.noteId);
        case "createNote":
            return await createNote(event.arguments.note);
        case "listNotes":
            return await listNotes();
        case "deleteNote":
            return await deleteNote(event.arguments.noteId);
        case "updateNote":
            return await updateNote(event.arguments.note);
        default:
            return null;
    }
}

Note.ts

// lambda-fns/Note.ts
interface Note {
  id: string;
  name: string;
  completed: boolean;
}

export = Note

createNote.ts

// lambda-fns/createNote.ts
const AWS = require('aws-sdk');
const docClient = new AWS.DynamoDB.DocumentClient();
import Note = require('./Note');

async function createNote(note: Note) {
    const params = {
        TableName: process.env.NOTES_TABLE,
        Item: note
    }
    try {
        await docClient.put(params).promise();
        return note;
    } catch (err) {
        console.log('DynamoDB error: ', err);
        return null;
    }
}

export default createNote;

deleteNote.ts

// lambda-fns/deleteNote.ts
const AWS = require('aws-sdk');
const docClient = new AWS.DynamoDB.DocumentClient();

async function deleteNote(noteId: String) {
    const params = {
        TableName: process.env.NOTES_TABLE,
        Key: {
          id: noteId
        }
    }
    try {
        await docClient.delete(params).promise()
        return noteId
    } catch (err) {
        console.log('DynamoDB error: ', err)
        return null
    }
}

export default deleteNote;

getNoteById.ts

// lambda-fns/appsync-ds-main.ts

const AWS = require('aws-sdk');
const docClient = new AWS.DynamoDB.DocumentClient();

async function getNoteById(noteId: String) {
    const params = {
        TableName: process.env.NOTES_TABLE,
        Key: { id: noteId }
    }
    try {
        const { Item } = await docClient.get(params).promise()
        return Item
    } catch (err) {
        console.log('DynamoDB error: ', err)
    }
}

export default getNoteById

listNotes.ts

// lambda-fns/listNotes.js
const AWS = require('aws-sdk');
const docClient = new AWS.DynamoDB.DocumentClient();

async function listNotes() {
    const params = {
        TableName: process.env.NOTES_TABLE,
    }
    try {
        const data = await docClient.scan(params).promise()
        return data.Items
    } catch (err) {
        console.log('DynamoDB error: ', err)
        return null
    }
}

export default listNotes;

updateNote.ts

// lambda-fns/updateNote.ts
const AWS = require('aws-sdk');
const docClient = new AWS.DynamoDB.DocumentClient();

interface Params {
  TableName: string | undefined,
  Key: string | {},
  ExpressionAttributeValues: any,
  ExpressionAttributeNames: any,
  UpdateExpression: string,
  ReturnValues: string
}

async function updateNote(note: any) {
  let params : Params = {
    TableName: process.env.NOTES_TABLE,
    Key: {
      id: note.id
    },
    ExpressionAttributeValues: {},
    ExpressionAttributeNames: {},
    UpdateExpression: "",
    ReturnValues: "UPDATED_NEW"
  };
  let prefix = "set ";
  let attributes = Object.keys(note);
  for (let i=0; i<attributes.length; i++) {
    let attribute = attributes[i];
    if (attribute !== "id") {
      params["UpdateExpression"] += prefix + "#" + attribute + " = :" + attribute;
      params["ExpressionAttributeValues"][":" + attribute] = note[attribute];
      params["ExpressionAttributeNames"]["#" + attribute] = attribute;
      prefix = ", ";
    }
 }
  console.log('params: ', params)
  try {
    await docClient.update(params).promise()
    return note
  } catch (err) {
    console.log('DynamoDB error: ', err)
    return null
  }
}

export default updateNote;

Deploying and testing

Now we are ready to deploy. To do so, run the following command from your terminal:

npm run build && cdk deploy

Now that the updates have been deployed, visit the AppSync console and click on the API name to view the dashboard for your API.

Next click on Queries in the left hand menu to view the query editor. From here, we can test out the API by running the following queries and mutations:

mutation createNote {
  createNote(note: {
    id: "001"
    name: "My note"
    completed: false
  }) {
    id
    name
    completed
  }
}

query getNoteById {
  getNoteById(noteId: "001") {
    id
    name
    completed
  }
}

query listNotes {
  listNotes {
    id
    name
    completed
  }
}

mutation updateNote {
  updateNote(note: {
    id: "001"
    completed: true
  }) {
    id
    completed
  }
}


mutation deleteNote {
  deleteNote(noteId: "001") 
}

Subscriptions

One of the most powerful components of a GraphQL API and one of the things that AppSync makes really easy is enabling real-time updates via GraphQL subscriptions.

GraphQL subscriptions allow you to subscribe to mutations made agains a GraphQL API. In our case, we may want to subscribe to changes like when a new note is created, when a note is deleted, or when a note is updated. To enable this, we can update the GraphQL schema with the following Subscription definitions:

# graphql/schema.graphql
type Subscription {
  onCreateNote: Note
    @aws_subscribe(mutations: ["createNote"])
  onDeleteNote: String
    @aws_subscribe(mutations: ["deleteNote"])
  onUpdateNote: Note
    @aws_subscribe(mutations: ["updateNote"])
}

Next, deploy the changes:

cdk deploy

To test out the changes, open another window and visit the AppSync Query editor for the GraphQL API.

From here, you can test out the subscription by running a subscription in one editor and triggering a mutation in another:

subscription onCreate {
  onCreateNote {
    id	
    name
    completed
  }
}

Connecting a Client application

You can connect to an AppSync API using the Amplify libraries for iOS, Android, or JavaScript.

In this example, we’ll walk through how you can make API calls from a JavaScript application.

Client project setup

You first need to install the AWS Amplify libraries using either NPM or Yarn.

npm install aws-amplify

Next, configure the Amplify app at the root of your project using the Project Region, API Key, and GraphQL URL. This information is available both in the AppSync dashboard for your API but also in the terminal after running cdk deploy. This configuration is usually done at the entry-point of your app:

  • Angular – main.ts
  • Vue – main.js 
  • React – index.js
  • Next.js – _app.js
import Amplify from 'aws-amplify';
Amplify.configure({
  aws_appsync_region: "us-east-1", // Stack region
  aws_appsync_graphqlEndpoint: "https://<app-id>.appsync-api.<region>.amazonaws.com/graphql", // AWS AppSync endpoint
  aws_appsync_authenticationType: "API_KEY", //Primary AWS AppSync authentication type
  aws_appsync_apiKey: "<YOUR_API_KEY>" // AppSync API Key
});

Fetching data (queries)

To query data, you can use the API category, passing in the query that you’d like to use. In our case, we’ll use the same query from above:

import { API } from 'aws-amplify'

const query = `
  query listNotes {
    listNotes {
      id name completed
    }
  }
`

async function fetchNotes(){
  const data = await API.graphql({ query })
  console.log('data from GraphQL:', data)
}

Updating data (mutations)

To create, update, or delete data, you can use the API category, passing in the mutation that you’d like to use along with any variables. In this example, we’ll look at how to create a new note:

import { API } from 'aws-amplify'

const mutation = `
  mutation createNote(note: NoteInput!) {
    createNote(note: $note) {
      id name completed
    }
  }
`

async function createNote() {
  await API.graphql({
    query: mutation,
    variables: { note: { id: '001', name: 'Note 1', completed: false } }
  })
  console.log('note successfully created!')
}

Real-time data (subscriptions)

To subscribe to real-time updates, we’ll use the API category and pass in the subscription we’d like to listen to. Any time a new mutation we are subscribed to happens, the data will be sent to the client application in real-time.

import { API } from 'aws-amplify'

const subscription = `
  subscription onCreateNote {
    onCreateNote {
      id name completed
    }
  }
`

function subscribe() {
  API.graphql({
    query: subscription
  })
  .subscribe({
    next: noteData => {
      console.log('noteData: ', noteData)
    }
  })
}

Conclusion

If you’d like to continue building this example out, you may look at implementing things like additional data sources, argument-based subscriptions, or creating and then querying against a DynamoDB Global Secondary Index.

If you’d like to see the code for this project, it is located here.