Connect to data from server-side runtimes
You can call an AppSync GraphQL API from a Node.js app or a Lambda function. Take a basic Todo app as an example:
type Todo @model @auth(rules: [{ allow: public }]) { name: String description: String}This API will have operations available for Query, Mutation, and Subscription. Let's take a look at how to perform both a query as well as a mutation from a Lambda function using Node.js.
First, create a Lambda function with amplify add function and make sure to give access to your GraphQL API when prompted by the CLI to grant access to other resources in the project.
amplify add function? Select which capability you want to add: Lambda function (serverless function)? Provide an AWS Lambda function name: myfunction? Choose the runtime that you want to use: NodeJS? Choose the function template that you want to use: Hello World
Available advanced settings:- Resource access permissions- Scheduled recurring invocation- Lambda layers configuration- Environment variables configuration- Secret values configuration
? Do you want to configure advanced settings? Yes? Do you want to access other resources in this project from your Lambda function? Yes? Select the categories you want this function to have access to. api? Select the operations you want to permit on <YOUR_API_NAME> Query, Mutation, Subscription
You can access the following resource attributes as environment variables from your Lambda function API_<YOUR_API_NAME>_GRAPHQLAPIENDPOINTOUTPUT API_<YOUR_API_NAME>_GRAPHQLAPIIDOUTPUT API_<YOUR_API_NAME>_GRAPHQLAPIKEYOUTPUT ENV REGIONThe examples on this page use node-fetch to make a HTTP request to your GraphQL API. When the Node.js v18 runtime is released for Lambda this dependency can be removed in favor of native fetch To get started, add the node-fetch module as a dependency:
{ "name": "myfunction",+ "type": "module", "version": "2.0.0", "description": "Lambda function generated by Amplify", "main": "index.js", "license": "Apache-2.0",+ "dependencies": {+ "node-fetch": "^3.2.3"+ }, "devDependencies": { "@types/aws-lambda": "^8.10.92" }}Query
Using an API Key for authenticating your requests, you can query the GraphQL API to get a list of all Todos.
import { default as fetch, Request } from 'node-fetch';
const GRAPHQL_ENDPOINT = process.env.API_<YOUR_API_NAME>_GRAPHQLAPIENDPOINTOUTPUT;const GRAPHQL_API_KEY = process.env.API_<YOUR_API_NAME>_GRAPHQLAPIKEYOUTPUT;
const query = /* GraphQL */ ` query LIST_TODOS { listTodos { items { id name description } } }`;
/** * @type {import('@types/aws-lambda').APIGatewayProxyHandler} */export const handler = async (event) => { console.log(`EVENT: ${JSON.stringify(event)}`);
/** @type {import('node-fetch').RequestInit} */ const options = { method: 'POST', headers: { 'x-api-key': GRAPHQL_API_KEY }, body: JSON.stringify({ query, variables }) };
const request = new Request(GRAPHQL_ENDPOINT, options);
let statusCode = 200; let body; let response;
try { response = await fetch(request); body = await response.json(); if (body.errors) statusCode = 400; } catch (error) { statusCode = 400; body = { errors: [ { status: response.status, message: error.message, stack: error.stack } ] }; }
return { statusCode, body: JSON.stringify(body) };};Mutation
In this example you create a mutation showing how to pass in variables as arguments to create a Todo record.
import { default as fetch, Request } from 'node-fetch';
const GRAPHQL_ENDPOINT = process.env.API_<YOUR_API_NAME>_GRAPHQLAPIENDPOINTOUTPUT;const GRAPHQL_API_KEY = process.env.API_<YOUR_API_NAME>_GRAPHQLAPIKEYOUTPUT;
const query = /* GraphQL */ ` mutation CREATE_TODO($input: CreateTodoInput!) { createTodo(input: $input) { id name createdAt } }`;
/** * @type {import('@types/aws-lambda').APIGatewayProxyHandler} */export const handler = async (event) => { console.log(`EVENT: ${JSON.stringify(event)}`);
const variables = { input: { name: 'Hello, Todo!' } };
/** @type {import('node-fetch').RequestInit} */ const options = { method: 'POST', headers: { 'x-api-key': GRAPHQL_API_KEY }, body: JSON.stringify({ query, variables }) };
const request = new Request(GRAPHQL_ENDPOINT, options);
let statusCode = 200; let body; let response;
try { response = await fetch(request); body = await response.json(); if (body.errors) statusCode = 400; } catch (error) { statusCode = 400; body = { errors: [ { status: response.status, message: error.message, stack: error.stack } ] }; }
return { statusCode, body: JSON.stringify(body) };};IAM Authorization
Let's take a look at another example schema that uses iam authorization.
type Todo @model @auth(rules: [{ allow: private, provider: iam }]) { name: String description: String}The CLI will automatically configure the Lambda execution IAM role to call the GraphQL API. Before writing your Lambda function you will first need to install the appropriate AWS SDK v3 dependencies:
{ "name": "myfunction",+ "type": "module", "version": "2.0.0", "description": "Lambda function generated by Amplify", "main": "index.js", "license": "Apache-2.0",+ "dependencies": {+ "@aws-crypto/sha256-js": "^2.0.1",+ "@aws-sdk/credential-provider-node": "^3.76.0",+ "@aws-sdk/protocol-http": "^3.58.0",+ "@aws-sdk/signature-v4": "^3.58.0",+ "node-fetch": "^3.2.3"+ }, "devDependencies": { "@types/aws-lambda": "^8.10.92" }}Then, the following example will sign the request to call the GraphQL API using IAM authorization.
import crypto from '@aws-crypto/sha256-js';import { defaultProvider } from '@aws-sdk/credential-provider-node';import { SignatureV4 } from '@aws-sdk/signature-v4';import { HttpRequest } from '@aws-sdk/protocol-http';import { default as fetch, Request } from 'node-fetch';
const { Sha256 } = crypto;const GRAPHQL_ENDPOINT = process.env.API_<YOUR_API_NAME>_GRAPHQLAPIENDPOINTOUTPUT;const AWS_REGION = process.env.AWS_REGION || 'us-east-1';
const query = /* GraphQL */ ` query LIST_TODOS { listTodos { items { id name description } } }`;
/** * @type {import('@types/aws-lambda').APIGatewayProxyHandler} */export const handler = async (event) => { console.log(`EVENT: ${JSON.stringify(event)}`);
const endpoint = new URL(GRAPHQL_ENDPOINT);
const signer = new SignatureV4({ credentials: defaultProvider(), region: AWS_REGION, service: 'appsync', sha256: Sha256 });
const requestToBeSigned = new HttpRequest({ method: 'POST', headers: { 'Content-Type': 'application/json', host: endpoint.host }, hostname: endpoint.host, body: JSON.stringify({ query }), path: endpoint.pathname });
const signed = await signer.sign(requestToBeSigned); const request = new Request(endpoint, signed);
let statusCode = 200; let body; let response;
try { response = await fetch(request); body = await response.json(); if (body.errors) statusCode = 400; } catch (error) { statusCode = 500; body = { errors: [ { message: error.message } ] }; }
return { statusCode, body: JSON.stringify(body) };};