Deploying Lambda Function GraphQL Resolvers

How to deploy serverless GraphQL APIs with custom Lambda resolvers using AWS Amplify and AWS AppSync

The Amplify CLI recently added support for deploying Lambda GraphQL resolvers directly from your Amplify environment. 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:

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:

  1. A Lambda resolver that talks to another API and returns a GraphQL response via a Query

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

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 template that you want to use: Hello world function
? Do you want to access other resources created in this project from your Lambda function? 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
? 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

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 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 uuid = require('uuid/v4')
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))

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

Nader Dabit

Web and mobile developer specializing in cross-platform and cloud-enabled application development.

Write your comment…

Hey Nader Dabit, thanks for the post!

When syndicating your content, make sure to republish posts properly and add the original URL. Hashnode and other publishing platforms support this feature which automatically adds the canonical tag to the page.

If you syndicate your content on other sites, Google will always show the version they think is most appropriate for users in each given search, which may or may not be the version you'd prefer. However, it is helpful to ensure that each site on which your content is syndicated includes a link back to your original article. Since your domain (dabit3.hashnode.dev) is fresh and not as strong as other platforms yet, your ranking can suffer.

Reply to this…

Wow, this looks neat. I’ve never tried AWS’ AppSync and Amplify.

I’ll keep this article in mind if I intend to use AWS in the future.

Reply to this…