Blog Home Category   Edition   Follow   Search Blogs 

AWS Mobile Blog

Building Scalable GraphQL APIs on AWS with CDK,

TypeScript, AWS AppSync, Amazon DynamoDB, and AWS
Lambda
by Nader Dabit | on 23 SEP 2020 | in Amazon DynamoDB, AWS Amplify, AWS AppSync, AWS Mobile Development, Mobile
Services, Top Posts | Permalink |  Comments |   Share

    https://aws.amazon.com/blogs/mobile/building-scalable-gra

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:

Bash
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:

Bash
aws configure

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

Bash
mkdir appsync-cdk-app

cd appsync-cdk-app

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

Bash
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:

Bash
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:

TypeScript
// 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:

TypeScript
// 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
# 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 the CDK diff command to see what changes will be deployed:

Bash
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:

Bash
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:

TypeScript
// 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:

GraphQL
// 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:

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

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

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

export = Note

createNote.ts

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

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

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

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

TypeScript
// 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:

Bash
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:

GraphQL
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
# 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:

Bash
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:

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

Bash
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

JavaScript
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.c
aws_appsync_authenticationType: "API_KEY", //Primary AWS AppSync authentication
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:

JavaScript
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:

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

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

Resources
AWS AppSync
AWS Device Farm
Amazon Pinpoint
AWS Amplify
 Follow
  AWS for Mobile
  Facebook
  LinkedIn
  Twitch
  Email Updates

Related Posts

How to delete user data in an AWS data lake

Instantly monitor serverless applications with AWS Resource Groups

Introducing immutable class mapping for the Enhanced DynamoDB Client in AWS SDK for Java 2.x

Build a compelling eCommerce experience with Amazon Interactive Video Service

Using the Amazon Chime SDK for 3rd party devices

Provisioning a Virtual Private Cloud at Scale with AWS CDK

Simplify Prior Authorization in Healthcare with AWS and HL7 FHIR

Unified serverless streaming ETL architecture with Amazon Kinesis Data Analytics