The Amplify CLI recently added support for deploying Lambda GraphQL resolvers directly from your Amplify environment for your AppSync APIs. Lambda function resolvers allow you to write your AppSync resolver logic in JavaScript.

Using the @function directive you can specify operations to interact with a Lambda function in your GraphQL schema:



type Mutation {
  addEntry(id: Int, email: String): String @function(name: "addEntry-${env}")
}

In this tutorial, I'll teach you how to create an application that uses two types of Lambda resolvers:

A Lambda resolver that talks to another API and returns a GraphQL response via a Query
A Lambda resolver that sends Queries and Mutations to interact with a real NoSQL database to perform Create and Read operations against it.

By the end of this tutorial, you should understand how to deploy an AppSync GraphQL API that interacts with Lambda GraphQL resolvers using the Amplify Framework.

To view the final source code for this project, click here.

Getting Started

To start things off, you'll need to create a new React application and initialize a new Amplify project within it:



npx create-react-app gql-lambda

cd gql-lambda

amplify init

# Follow the steps to give the project a name, environment name, and set the default text editor.
# Accept defaults for everything else and choose your AWS Profile.

If you don't yet have the Amplify CLI installed and configured, follow the directions here.

Next, install the AWS Amplify library:



npm install aws-amplify

Creating the API

The first GraphQL API we'll create is one that will query data from another REST API and return a GraphQL response. The API that you'll be interacting with is the Coinlore API.

Let's first create the function:



amplify add function

? Provide a friendly name for your resource to be used as a label for this category in the project: currencyfunction
? Provide the AWS Lambda function name: currencyfunction
? Choose the function runtime that you want to use: NodeJS
? Choose the function template that you want to use: Hello world
? Do you want to access other resources created in this project from your Lambda function? N
? Do you want to invoke this function on a recurring schedule? N
? Do you want to edit the local lambda function now? Y

Update the function with the following code:



// amplify/backend/function/currencyfunction/src/index.js
const axios = require('axios')

exports.handler = function (event, _, callback) {
  let apiUrl = `https://api.coinlore.com/api/tickers/?start=1&limit=10`

  if (event.arguments) { 
    const { start = 0, limit = 10 } = event.arguments
    apiUrl = `https://api.coinlore.com/api/tickers/?start=${start}&limit=${limit}`
  }

  axios.get(apiUrl)
    .then(response => callback(null, response.data.data))
    .catch(err => callback(err))
}

In the above function we've used the axios library to call another API. In order to use axios, we need to install it in the function folder. We'll also install uuid for later use:



cd amplify/backend/function/currencyfunction/src

npm install axios uuid

cd ../../../../../

Now that the function has been created, we'll need to create the GraphQL API. To do so, run the Amplify add command:



amplify add api

? Please select from one of the below mentioned services: GraphQL
? Provide API name: currencyapi
? Choose an authorization type for the API: API key
? Enter a description for the API key: public
? After how many days from now the API key should expire (1-365): 365 (or your preferred expiration)
? Do you want to configure advanced settings for the GraphQL API: N
? Do you have an annotated GraphQL schema? N
? Do you want a guided schema creation? Y
? What best describes your project: Single object with fields
? Do you want to edit the schema now? Y

Next, in amplify/backend/api/currencyapi/schema.graphql, update the schema with the following:



type Coin {
  id: String!
  name: String!
  symbol: String!
  price_usd: String!
}

type Query {
  getCoins(limit: Int start: Int): [Coin] @function(name: "currencyfunction-${env}")
}

Now the API and Lambda function have both been created. To deploy them and make them live, you can run the push command:



amplify push

Current Environment: dev

| Category | Resource name    | Operation | Provider plugin   |
| -------- | -------------    | --------- | ----------------- |
| Api      | currencyapi      | Create    | awscloudformation |
| Function | currencyfunction | Create    | awscloudformation |
? Are you sure you want to continue? (Y/n) Y

Now, the resources have been deployed and you can try out the query! You can test the query out in the AWS AppSync console. To open the API dashboard, run the following command in your terminal:



amplify console api

? Please select from one of the below mentioned services: GraphQL

In the query editor, run the following queries:



# basic request
query listCoins {
  getCoins {
    price_usd
    name
    id
    symbol
  }
}

# request with arguments
query listCoinsWithArgs {
  getCoins(limit:3 start: 10) {
    price_usd
    name
    id
    symbol
  }
}

This query should return an array of cryptocurrency information.

Updating the API to perform CRUD operations against a NoSQL database

Now that the basic API is up and running, let's create a database and update the API to perform create and read operations against it.

To get started, we'll create the database:



amplify add storage

? Please select from one of the below mentioned services: NoSQL Database
? Please provide a friendly name for your resource that will be used to label this category in the project: currencytable
? Please provide table name: currencytable
? What would you like to name this column: id
? Please choose the data type: string
? Would you like to add another column? Y
? What would you like to name this column: name
? Please choose the data type: string
? Would you like to add another column? Y
? What would you like to name this column: symbol
? Please choose the data type: string
? Would you like to add another column? Y
? What would you like to name this column: price_usd
? Please choose the data type: string
? Would you like to add another column? N
? Please choose partition key for the table: id
? Do you want to add a sort key to your table? N
? Do you want to add global secondary indexes to your table? N
? Do you want to add a Lambda Trigger for your Table? N

Next, let's update the function to use the new database.



amplify update function

? Please select the Lambda Function you would want to update: currencyfunction
? Do you want to update permissions granted to this Lambda function to perform on other resources in your project? Y
? Select the category: storage
? Select the operations you want to permit for currencytable:
  ◉ create
  ◉ read
  ◉ update
 ❯◉ delete
? Do you want to invoke this function on a recurring schedule? N
? Do you want to edit the local lambda function now? Y

Next, we'll update the lambda function. Right now the function code lives on only one file, index.js located at amplify/backend/function/currencyfunction/src/index.js. In the src folder, create two new files: createCoin.js and getCoins.js. In the next steps, we'll update index.js and also populate the other two new files with code.

index.js



const getCoins = require('./getCoins')
const createCoin = require('./createCoin')

exports.handler = function (event, _, callback) {
  if (event.typeName === 'Mutation') {
    createCoin(event, callback)
  }
  if (event.typeName === 'Query') {
    getCoins(callback)
  }
}

In the event argument to the function, there is a typeName field that will tell us if the operation is a Mutation or Query. There is also a fieldName argument that will tell you the actual field being executed if you have multiple Queries or Mutations.

We will use the typeName field to call either createCoin or getCoins based on the type of operation.

getCoins.js



const AWS = require('aws-sdk')
const region = process.env.REGION
const storageCurrencytableName = process.env.STORAGE_CURRENCYTABLE_NAME
const docClient = new AWS.DynamoDB.DocumentClient({region})

const params = {
  TableName: storageCurrencytableName
}

function getCoins(callback) {
  docClient.scan(params, function(err, data) {
    if (err) {
      callback(err)
    } else {
      callback(null, data.Items)
    }
  });
}

module.exports = getCoins

In getCoins we call a DynamoDB scan operation to read the database and return all of the values in an array. We also use the DynamoDB.DocumentClient sdk to simplify working with items in Amazon DynamoDB with JavaScript.

createCoin.js



const AWS = require('aws-sdk')
const { v4: uuid } = require('uuid')
const region = process.env.REGION
const ddb_table_name = process.env.STORAGE_CURRENCYTABLE_NAME
const docClient = new AWS.DynamoDB.DocumentClient({region})

function write(params, event, callback){
  docClient.put(params, function(err, data) {
    if (err) {
      callback(err)
    } else {
      callback(null, event.arguments)
    }
  })
}

function createCoin(event, callback) {
  const args = { ...event.arguments, id: uuid() }
  var params = {
    TableName: ddb_table_name,
    Item: args
  };

  if (Object.keys(event.arguments).length > 0) {
    write(params, event, callback)
  } 
}

module.exports = createCoin

In createCoin we do a putItem operation against the DynamoDB table passing in the arguments. We also auto-generate and ID on the server to populate a unique ID for the item using the uuid library.

Finally, we'll update the GraphQL Schema at amplify/backend/api/currencyapi/schema.graphql to add the mutation definition:



# amplify/backend/api/currencyapi/schema.graphql

type Coin {
  id: String!
  name: String!
  symbol: String!
  price_usd: String!
}

type Query {
  getCoins(limit: Int start: Int): [Coin] @function(name: "currencyfunction-${env}")
}

# new mutation definition
type Mutation {
  createCoin(name: String! symbol: String! price_usd: String!): Coin @function(name: "currencyfunction-${env}")
}

Now, deploy the changes:



amplify push

Testing it out

Now, the resources have been deployed and you can try out the query! You can test the query out in the AWS AppSync console. To open your project, run the following command in your terminal:



amplify console api

? Please select from one of the below mentioned services: GraphQL

Test out the following queries:



query listCoins {
  getCoins {
    price_usd
    name
    id
    symbol
  }
}

mutation createCoin {
  createCoin(
    name: "Monero"
    price_usd: "86.85"
    symbol: "XMR"
  ) {
    name price_usd symbol
  }
}

Testing it out on the client

If you'd like to test it out in the React application, you can use the API category from Amplify:



import { API, graphqlOperation } from 'aws-amplify'
import { getCoins } from './graphql/queries'
import { createCoin } from './graphql/mutations'

// mutation
const coin = { name: "Bitcoin", symbol: "BTC", price: "10000" }
API.graphql(graphqlOperation(createCoin, coin))
  .then(data => console.log({ data }))
  .catch(err => console.log('error: ', err))

// query
API.graphql(graphqlOperation(getCoins))
  .then(data => console.log({ data }))
  .catch(err => console.log('error: ', err))