Tutorial: Pipeline Resolvers

AWS AppSync provides a simple way to wire a GraphQL field to a single data source through unit resolvers. However, executing a single operation might not be enough. Pipeline resolvers offer the ability to serially execute operations against data sources. Create functions in your API and attach them to a pipeline resolver. Each function execution result is piped to the next until no function is left to execute. With pipeline resolvers you can now build more complex workflows directly in AWS AppSync. In this tutorial, you build a simple pictures viewing app, where users can post and view pictures posted by their friends.

One-Click Setup

If you want to automatically set up the GraphQL endpoint in AWS AppSync with all the resolvers configured and the necessary AWS resources, you can use the following AWS CloudFormation template :

This stack creates the following resources in your account:

At the end of the AWS CloudFormation stack creation process you receive one email for each of the three Amazon Cognito users that were created. Each email contains a temporary password that you use to log in as an Amazon Cognito user to the AWS AppSync console. Save the passwords for the remainder of the tutorial.

Manual Setup

If you prefer to manually go through a step-by-step process through the AWS AppSync console, follow the setup process below.

Setting Up Your Non AWS AppSync Resources

The API communicates with two DynamoDB tables: a pictures table that stores pictures and a friends table that stores relationships between users. The API is configured to use Amazon Cognito user pool as authentication type. The following AWS CloudFormation stack sets up these resources in the account.

At the end of the AWS CloudFormation stack creation process you receive one email for each of the three Amazon Cognito users that were created. Each email contains a temporary password that you use to log in as an Amazon Cognito user to the AWS AppSync console. Save the passwords for the remainder of the tutorial.

Creating Your GraphQL API

To create the GraphQL API in AWS AppSync:

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.

Configuring The GraphQL API

You need to configure the AWS AppSync API with the Amazon Cognito user pool that you just created.

The API is now set up to use Amazon Cognito user pool as its authorization type.

Configuring Data Sources for the DynamoDB Tables

After the DynamoDB tables have been created, navigate to your AWS AppSync GraphQL API in the console and choose the Data Sources tab. Now, you’re going to create a datasource in AWS AppSync for each of the DynamoDB tables that you just created.

Repeat the same process for the friends table, the name of the DynamoDB table should be AppSyncTutorial-Friends if you did not change the ResourceNamePrefix parameter at the time of creating the CloudFormation stack.

Creating the GraphQL Schema

Now that the data sources are connected to your DynamoDB tables, let’s create a GraphQL schema. From the schema editor in the AWS AppSync console, make sure your schema matches the following schema:

schema {
    query: Query
    mutation: Mutation
}

type Mutation {
    createPicture(input: CreatePictureInput!): Picture!
    @aws_auth(cognito_groups: ["Admins"])
    createFriendship(id: ID!, target: ID!): Boolean
    @aws_auth(cognito_groups: ["Admins"])
}

type Query {
    getPicturesByOwner(id: ID!): [Picture]
    @aws_auth(cognito_groups: ["Admins", "Viewers"])
}

type Picture {
    id: ID!
    owner: ID!
    src: String
}

input CreatePictureInput {
    owner: ID!
    src: String!
}

Choose Save Schema to save your schema.

Some of the schema fields have been annotated with the @aws_auth directive. Since the API default action configuration is set to DENY, the API rejects all users that are not members of the groups mentioned inside the @aws_auth directive. For more information about how to secure your API, you can read the Security page. In this case, only admin users have access to the Mutation.createPicture and Mutation.createFriendship fields, while users that are members of either Admins or Viewers groups can access the Query.getPicturesByOwner field. All other users don’t have access.

Configuring Resolvers

Now that you have a valid GraphQL schema and two data sources, you can attach resolvers to the GraphQL fields on the schema. The API offers the following capabilities:

Mutation.createPicture

From the schema editor in the AWS AppSync console, on the right side choose Attach Resolver for createPicture(input: CreatePictureInput!): Picture!. Choose the DynamoDBPicturesDynamoDBTable data source. In the request mapping template section, add the following template:

#set($id = $util.autoId())

{
    "version" : "2018-05-29",

    "operation" : "PutItem",

    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($id),
        "owner": $util.dynamodb.toDynamoDBJson($ctx.args.input.owner)
    },

    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args.input)
}

In the response mapping template section, add the following template:

#if($ctx.error)
    $util.error($ctx.error.message, $ctx.error.type)
#end
$util.toJson($ctx.result)

The create picture functionality is done. You are saving a picture in the Pictures table, using a randomly generated UUID as id of the picture, and using the Cognito username as owner of the picture.

Mutation.createFriendship

From the schema editor in the AWS AppSync console, on the right side choose Attach Resolver for createFriendship(id: ID!, target: ID!): Boolean. Choose the DynamoDBFriendsDynamoDBTable data source. In the request mapping template section, add the following template:

#set($userToFriendFriendship = { "userId" : "$ctx.args.id", "friendId": "$ctx.args.target" })
#set($friendToUserFriendship = { "userId" : "$ctx.args.target", "friendId": "$ctx.args.id" })
#set($friendsItems = [$util.dynamodb.toMapValues($userToFriendFriendship), $util.dynamodb.toMapValues($friendToUserFriendship)])

{
    "version" : "2018-05-29",
    "operation" : "BatchPutItem",
    "tables" : {
        ## Replace 'AppSyncTutorial-' default below with the ResourceNamePrefix you provided in the CloudFormation template
        "AppSyncTutorial-Friends": $util.toJson($friendsItems)
    }
}

Important: In the BatchPutItem request template, the exact name of the DynamoDB table should be present. The default table name is AppSyncTutorial-Friends. If you are using the wrong table name, you get an error when AppSync tries to assume the provided role.

For the sake of simplicity in this tutorial, proceed as if the friendship request has been approved and save the relationship entry directly into the AppSyncTutorialFriends table.

Effectively, you’re storing two items for each friendship as the relationship is bi-directional. For more details about Amazon DynamoDB best practices to represent many-to-many relationships, see DynamoDB Best Practices .

In the response mapping template section, add the following template:

#if($ctx.error)
    $util.error($ctx.error.message, $ctx.error.type)
#end
true

Note: Make sure your request template contains the right table name. The default name is AppSyncTutorial-Friends, but your table name might differ if you changed the CloudFormation ResourceNamePrefix parameter.

Query.getPicturesByOwner

Now that you have friendships and pictures, you need to provide the ability for users to view their friends’ pictures. To satisfy this requirement, you need to first check that the requester is friend with the owner, and finally query for the pictures.

Because this functionality requires two data source operations, you’re going to create two functions. The first function, isFriend, checks whether the requester and the owner are friends. The second function, getPicturesByOwner, retrieves the requested pictures given an owner ID. Let’s look at the execution flow below for the proposed resolver on the Query.getPicturesByOwner field:

Let’s first create the functions.

isFriend Function

Result: You’ve created the isFriend function.

getPicturesByOwner function

Result: You’ve created the getPicturesByOwner function. Now that the functions have been created, attach a pipeline resolver to the Query.getPicturesByOwner field.

From the schema editor in the AWS AppSync console, on the right side choose Attach Resolver for Query.getPicturesByOwner(id: ID!): [Picture]. On the following page, choose the Convert to pipeline resolver link that appears underneath the data source drop-down list. Use the following for the before mapping template:

#set($result = { "owner": $ctx.args.id, "callerId": $ctx.identity.username })
$util.toJson($result)

In the after mapping template section, use the following:

#foreach($picture in $ctx.result.items)
    ## prepend "src://" to picture.src property
    #set($picture['src'] = "src://${picture['src']}")
#end
$util.toJson($ctx.result.items)

Choose Create Resolver. You have successfully attached your first pipeline resolver. On the same page, add the two functions you created previously. In the functions section, choose Add A Function and then choose or type the name of the first function, isFriend. Add the second function by following the same process for the getPicturesByOwner function. Make sure the isFriend function appears first in the list followed by the getPicturesByOwner function. You can use the up and down arrows to rearrange to order of execution of the functions in the pipeline.

Now that the pipeline resolver is created and you’ve attached the functions, let’s test the newly created GraphQL API.

Testing Your GraphQL API

First, you need to populate pictures and friendships by executing a few mutations using the admin user you created. On the left side of the AWS AppSync console, choose the Queries tab.

createPicture Mutation

Let’s send a few createPicture mutations to populate the pictures table. Execute the following GraphQL query inside the console:

mutation {
  createPicture(input:{
    owner: "nadia"
    src: "nadia.jpg"
  }) {
    id
    owner
    src
  }
}

The response should look like below:

{
  "data": {
    "createPicture": {
      "id": "c6fedbbe-57ad-4da3-860a-ffe8d039882a",
      "owner": "nadia",
      "src": "nadia.jpg"
    }
  }
}

Let’s add a few more pictures:

mutation {
  createPicture(input:{
    owner: "shaggy"
    src: "shaggy.jpg"
  }) {
    id
    owner
    src
  }
}

mutation {
  createPicture(input:{
    owner: "rex"
    src: "rex.jpg"
  }) {
    id
    owner
    src
  }
}

You’ve added three pictures using nadia as the admin user.

createFriendship Mutation

Let’s add a friendship entry. Execute the following mutations in the console.

Note: You must still be logged in as the admin user (the default admin user is nadia).

mutation {
  createFriendship(id: "nadia", target: "shaggy")
}

The response should look like:

{
  "data": {
    "createFriendship": true
  }
}

nadia and shaggy are friends. rex is not friends with anybody.

getPicturesByOwner Query

For this step, log in as the nadia user using Cognito User Pools, using the credentials set up in the beginning of this tutorial. As nadia, retrieve the pictures owned by shaggy.

query {
    getPicturesByOwner(id: "shaggy") {
        id
        owner
        src
    }
}

Since nadia and shaggy are friends, the query should return the corresponding picture.

{
  "data": {
    "getPicturesByOwner": [
      {
        "id": "05a16fba-cc29-41ee-a8d5-4e791f4f1079",
        "owner": "shaggy",
        "src": "src://shaggy.jpg"
      }
    ]
  }
}

Similarly, if nadia attempts to retrieve her own pictures, it also succeeds. The pipeline resolver has been optimized to avoid running the isFriend GetItem operation in that case. Try the following query:

query {
    getPicturesByOwner(id: "nadia") {
        id
        owner
        src
    }
}

If you enable logging on your API (in the Settings pane), set the debug level to ALL, and run the same query again, it returns logs for the field execution. By looking at the logs, you can determine whether the isFriend function returned early at the Request Mapping Template stage:

{
  "errors": [],
  "mappingTemplateType": "Request Mapping",
  "path": "[getPicturesByOwner]",
  "resolverArn": "arn:aws:appsync:us-west-2:XXXX:apis/XXXX/types/Query/fields/getPicturesByOwner",
  "functionArn": "arn:aws:appsync:us-west-2:XXXX:apis/XXXX/functions/o2f42p2jrfdl3dw7s6xub2csdfs",
  "functionName": "isFriend",
  "earlyReturnedValue": {
    "owner": "nadia",
    "callerId": "nadia"
  },
  "context": {
    "arguments": {
      "id": "nadia"
    },
    "prev": {
      "result": {
        "owner": "nadia",
        "callerId": "nadia"
      }
    },
    "stash": {},
    "outErrors": []
  },
  "fieldInError": false
}

The earlyReturnedValue key represents the data that was returned by the #return directive.

Finally, even though rex is a member of the Viewers Cognito UserPool Group, and because rex isn’t friends with anybody, he won’t be able to access any of the pictures owned by shaggy or nadia. If you log in as rex in the console and execute the following query:

query {
    getPicturesByOwner(id: "nadia") {
        id
        owner
        src
    }
}

You get the following unauthorized error:

{
  "data": {
    "getPicturesByOwner": null
  },
  "errors": [
    {
      "path": [
        "getPicturesByOwner"
      ],
      "data": null,
      "errorType": "Unauthorized",
      "errorInfo": null,
      "locations": [
        {
          "line": 2,
          "column": 9,
          "sourceName": null
        }
      ],
      "message": "Not Authorized to access getPicturesByOwner on type Query"
    }
  ]
}

You have successfully implemented complex authorization using pipeline resolvers.