AWS AppSync resolver mapping template changelog

Resolver and function mapping templates are versioned. The mapping template version, such as 2018-05-29) dictates the following:

Versions are represented using the YYYY-MM-DD format, a later date corresponds to a more recent version. This page lists the differences between the mapping template versions currently supported in AWS AppSync.

Datasource Operation Availability Per Version Matrix

Note: Only 2018-05-29 version is currently supported in functions.

Changing the Version on a Unit Resolver Mapping Template

For Unit resolvers, the version is specified as part of the body of the request mapping template. To update the version, simply update the version field to the new version.

For example, to update the version on the AWS Lambda template:

{
    "version": "2017-02-28",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "arguments": $utils.toJson($context.arguments)
    }
}

You need to update the version field from 2017-02-28 to 2018-05-29 as follows:

{
    "version": "2018-05-29", ## Note the version
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "arguments": $utils.toJson($context.arguments)
    }
}

Changing the Version on a Function

For functions, the version is specified as the functionVersion field on the function object. To update the version, simply update the functionVersion. Note: Currently, only 2018-05-29 is supported for function.

The following is an example of a CLI command to update an existing function version:

aws appsync update-function \
--api-id REPLACE_WITH_API_ID \
--function-id REPLACE_WITH_FUNCTION_ID \
--data-source-name "PostTable" \
--function-version "2018-05-29" \
--request-mapping-template "{...}" \
--response-mapping-template "\$util.toJson(\$ctx.result)"

Note: It is recommended to omit the version field from the function request mapping template as it will not be honored. If you do specify a version inside a function request mapping template, the version value will be overridden by the value of the functionVersion field.

2018-05-29

Behavior Change

Reasoning

Given the following response mapping template:

$util.toJson($ctx.result)

Previously with 2017-02-28, if $ctx.result came back null, the response mapping template was not executed. With 2018-05-29, we can now handle this scenario. For example, we can choose to raise an authorization error as follows:

# throw an unauthorized error if the result is null
#if ( $util.isNull($ctx.result) )
    $util.unauthorized()
#end
$util.toJson($ctx.result)

Note: Errors coming back from a data source are sometimes not fatal or even expected, that is why the response mapping template should be given the flexibility to handle the invocation error and decide whether to ignore it, re-raise it, or throw a different error.

Given the following response mapping template:

$util.toJson($ctx.result)

Previously, with 2017-02-28, in case of an invocation error, the response mapping template was evaluated and the result was placed automatically in the errors block of the GraphQL response. With 2018-05-29, we can now choose what to do with the error, re-raise it, raise a different error, or append the error while return data.

Re-raise an Invocation Error

In the following response template, we raise the same error that came back from the data source.

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

In case of an invocation error (for example, $ctx.error is present) the response looks like the following:

{
    "data": {
        "getPost": null
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "DynamoDB:ConditionalCheckFailedException",
            "message": "Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}

Raise a Different Error

In the following response template, we raise our own custom error after processing the error that came back from the data source.

#if ( $ctx.error )
    #if ( $ctx.error.type.equals("ConditionalCheckFailedException") )
        ## we choose here to change the type and message of the error for ConditionalCheckFailedExceptions
        $util.error("Error while updating the post, try again. Error: $ctx.error.message", "UpdateError")
    #else
        $util.error($ctx.error.message, $ctx.error.type)
    #end
#end
$util.toJson($ctx.result)

In case of an invocation error (for example, $ctx.error is present) the response looks like the following:

{
    "data": {
        "getPost": null
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "UpdateError",
            "message": "Error while updating the post, try again. Error: Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}

Append an Error to Return Data

In the following response template, we append the same error that came back from the data source while returning data back inside the response. This is also known as a partial response.

#if ( $ctx.error )
    $util.appendError($ctx.error.message, $ctx.error.type)
    #set($defaultPost = {id: "1", title: 'default post'})
    $util.toJson($defaultPost)
#else
    $util.toJson($ctx.result)
#end

In case of an invocation error (for example, $ctx.error is present) the response looks like the following:

{
    "data": {
        "getPost": {
            "id": "1",
            "title: "A post"
        }
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "ConditionalCheckFailedException",
            "message": "Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}

Migrating from 2017-02-28 to 2018-05-29

Migrating from 2017-02-28 to 2018-05-29 is straightforward. Change the version field on the resolver request mapping template or on the function version object. However, note that 2018-05-29 execution behaves differently from 2017-02-28, changes are outlined here.

Preserving the same execution behavior from 2017-02-28 to 2018-05-29

In some cases, it is possible to retain the same execution behavior as the 2017-02-28 version while executing a 2018-05-29 versioned template.

Example: DynamoDB PutItem

Given the following 2017-02-28 DynamoDB PutItem request template:

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    }
}

And the following response template:

$util.toJson($ctx.result)

Migrating to 2018-05-29 changes these templates as follows:

{
    "version" : "2018-05-29", ## Note the new 2018-05-29 version
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    }
}

And changes the response template as follows:

## If there is a datasource invocation error, we choose to raise the same error
## the field data will be set to null.
#if($ctx.error)
  $util.error($ctx.error.message, $ctx.error.type, $ctx.result)
#end

## If the data source invocation is null, we return null.
#if($util.isNull($ctx.result))
  #return
#end

$util.toJson($ctx.result)

Now that it is your responsibility to handle errors, we chose to raise the same error using $util.error() that was returned from DynamoDB. You can adapt this snippet to convert your mapping template to 2018-05-29, note that if your response template is different you will have to take account of the execution behavior changes.

Example: DynamoDB GetItem

Given the following 2017-02-28 DynamoDB GetItem request template:

{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}

And the following response template:

## map table attribute postId to field Post.id
$util.qr($ctx.result.put("id", $ctx.result.get("postId")))

$util.toJson($ctx.result)

Migrating to 2018-05-29 changes these templates as follows:

{
    "version" : "2018-05-29", ## Note the new 2018-05-29 version
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}

And changes the response template as follows:

## If there is a datasource invocation error, we choose to raise the same error
#if($ctx.error)
  $util.error($ctx.error.message, $ctx.error.type)
#end

## If the data source invocation is null, we return null.
#if($util.isNull($ctx.result))
  #return
#end

## map table attribute postId to field Post.id
$util.qr($ctx.result.put("id", $ctx.result.get("postId")))

$util.toJson($ctx.result)

In the 2017-02-28 version, if the datasource invocation was null, meaning there is no item in the DynamoDB table that matches our key, the response mapping template would not execute. It might be fine for most of the cases, but if you expected the $ctx.result to not be null, you now have to handle that scenario.

2017-02-28

Characteristics