AWS AppSync
AWS AppSync Developer Guide

Tutorial: HTTP Resolvers

AWS AppSync enables you to use supported data sources (AWS Lambda, Amazon DynamoDB, or Amazon Elasticsearch Service) to perform various operations, in addition to any arbitrary HTTP endpoints to resolve GraphQL fields. After your HTTP endpoints are available, you can connect to them using a data source. Then, you can configure a resolver in the schema to perform GraphQL operations such as queries, mutations, and subscriptions. This tutorial walks you through some common examples.

In this tutorial we are going to front a REST API (created using Amazon API Gateway and Lambda) with AWS AppSync GraphQL endpoint.

One-Click Setup

If you want to automatically set up a GraphQL endpoint in AWS AppSync with an HTTP endpoint (using Amazon API Gateway and Lambda) configured, you can use the following AWS CloudFormation template:

Creating a REST API

You can use the following AWS CloudFormation template to set up a REST endpoint that will work for the following tutorial.

The cloud formation stack performs the following steps:

  1. Sets up a Lambda function, which contains your business logic for your microservice.

  2. Sets up an API Gateway REST API with the following endpoint/method/content type combination:

API Resource Path HTTP Method Supported Content Type

/v1/users

POST

application/xml

/v1/users/1

GET

application/json

/v1/users/1

PUT

application/json

/v1/users/1

DELETE

application/json

Creating Your GraphQL API

To create the GraphQL API in AWS AppSync:

  • Open the AWS AppSync console and choose Create API.

  • Set the name of the API to UserData.

  • Choose Custom schema.

  • Choose Create.

The AWS AppSync console creates a new GraphQL API for you using the API key authentication mode. You can use the console to set up the rest of the GraphQL API and run queries against it for the rest of this tutorial.

Creating a GraphQL Schema

Now that you have a GraphQL API, let's create a GraphQL schema. From the schema editor in the AWS AppSync console, make sure you schema matches the following schema:

schema { query: Query mutation: Mutation } type Mutation { addUser(userInput: UserInput!): User deleteUser(id: ID!): User } type Query { getUser(id: ID): User } type User { id: ID! username: String! firstname: String lastname: String phone: String email: String } input UserInput { id: ID! username: String! firstname: String lastname: String phone: String email: String }

Configure Your HTTP Data Source

To configure your HTTP data source, do the following:

  • On the DataSources tab, choose New, and then type a friendly name for the data source (for example, "HTTP").

  • In Data source type, choose HTTP.

  • Set the endpoint to the API Gateway endpoint that is created. Make sure that you don't include the stage name as part of the endpoint.

Note: At this time only endpoints that are publicly accessible are supported by AWS AppSync.

Note: Take a look at the certifying authorities that are recognized by the AWS AppSync service here.

Configuring resolvers

In this step, you connect the http data source to the getUser Query.

To set up the resolver:

  • Choose the Schema tab.

  • In the Data types pane on the right, find the getUser field on the Query type.

  • Choose Attach.

  • In Data source name, choose HTTP.

  • In Configure the request mapping template, paste the following:

{ "version": "2018-05-29", "method": "GET", "params": { "headers": { "Content-Type": "application/json" } }, "resourcePath": "/v1/users/${ctx.args.id}" }
  • In Configure the response mapping template, paste the following:

## return the body #if($ctx.result.statusCode == 200) ##if response is 200 $ctx.result.body #else ##if response is not 200, append the response to error block. $utils.appendError($ctx.result.body, $ctx.result.statusCode) #end
  • Choose the Query tab, and then run the following query:

query{ getUser(id:1){ name height } }

This should return the following response:

{ "data": { "getUser": { "id": "1", "username": "nadia" } } }

Now, let's try to return the home world or the planet of every time we query a person by planet. To set up the homeworld, do the following:

  • Choose the Schema tab.

  • In the Data types pane on the right, find the addUser field on the Mutation type.

  • Choose Attach.

  • In Data source name, choose HTTP.

  • In Configure the request mapping template, paste the following:

#set($xml = "<User>") #foreach ($mapEntry in $ctx.args.userInput.entrySet()) #set($xml = "$xml<$mapEntry.key>$mapEntry.value</$mapEntry.key>") #end #set($xml = "$xml</User>") { "version": "2018-05-29", "method": "POST", "params": { "headers":{ "Content-Type":"application/xml" }, "body":"$xml" }, "resourcePath": "/v1/users" }
  • In Configure the response mapping template, paste the following:

## return the body #if($ctx.result.statusCode == 200) ##if response is 200 ## Since the response is of type XML, we are going to convert ## the result body as a map and only get the User object. $utils.toJson($utils.xml.toMap($ctx.result.body).User) #else ##if response is not 200, append the response to error block. $utils.appendError($ctx.result.body, $ctx.result.statusCode) #end
  • Choose the Query tab, and then run the following query:

mutation{ addUser(userInput:{ id:"2", username:"shaggy" }){ id username } }

This should return the following response:

{ "data": { "getUser": { "id": "2", "username": "shaggy" } } }