Set up data transformations in API Gateway

To create an Amazon CloudFormation stack

1. Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

2. Choose Create stack and then choose With new resources (standard).

3. For Specify template, choose Upload a template file.

4. Select the template that you downloaded.

5. Choose Next.

6. For Stack name, enter data-transformation-tutorial-console and then choose Next.

7. For Configure stack options, choose Next.

8. For Capabilities, acknowledge that Amazon CloudFormation can create IAM resources in your account.

9. Choose Submit.

To test the GET integration response

1. On the Resources tab of the Amazon CloudFormation stack for data-transformation-tutorial-console, select the physical ID of your API.

2. In the main navigation pane, choose Resources, and then select the GET method.

3. Choose the Test tab. You might need to choose the right arrow button to show the tab.

   The output of the test will show the following:

   [
     {
       "id": 1,
       "type": "dog",
       "price": 249.99
     },
     {
       "id": 2,
       "type": "cat",
       "price": 124.99
     },
     {
       "id": 3,
       "type": "fish",
       "price": 0.99
     }
   ]

   You will transform this output according to the mapping template in PetStore mapping template.

To transform the GET integration response

1. Choose the Integration response tab.

   Currently, there are no mapping templates defined, so the integration response will not be transformed.

2. For Default - Response, choose Edit.

3. Choose Mapping templates, and then do the following:

   1. Choose Add mapping template.

   2. For Content type, enter application/json.

   3. For Template body, enter the following:

      #set($inputRoot = $input.path('$'))
      [
      #foreach($elem in $inputRoot)
        {
          "description" : "Item $elem.id is a $elem.type.",
          "askingPrice" : $elem.price
        }#if($foreach.hasNext),#end
      
      #end
      ]

   Choose Save.

To test the GET integration response

• Choose the Test tab, and then choose Test.

  The output of the test will show the transformed response.

  [
    {
      "description" : "Item 1 is a dog.",
      "askingPrice" : 249.99
    },
    {
      "description" : "Item 2 is a cat.",
      "askingPrice" : 124.99
    },
    {
      "description" : "Item 3 is a fish.",
      "askingPrice" : 0.99
    }
  ]

To transform input data from the POST method

1. Choose the POST method.

2. Choose the Integration request tab, and then for Integration request settings, choose Edit.

   The Amazon CloudFormation template has populated some of the integration request fields.

   • The integration type is Amazon Web Service.

   • The Amazon Web Service is DynamoDB.

   • The HTTP method is POST.

   • The Action is PutItem.

   • The Execution role allowing API Gateway to put an item into the DynamoDB table is data-transformation-tutorial-console-APIGatewayRole. Amazon CloudFormation created this role to allow API Gateway to have the minimal permissions for interacting with DynamoDB.

   The name of the DynamoDB table has not been specified. You will specify the name in the following steps.

3. For Request body passthrough, select Never.

   This means that the API will reject data with Content-Types that do not have a mapping template.

4. Choose Mapping templates.

5. The Content type is set to application/json. This means a content types that are not application/json will be rejected by the API. For more information about the integration passthrough behaviors, see Integration passthrough behaviors

6. Enter the following code into the text editor.

   {
       "TableName":"data-transformation-tutorial-console-ddb",
       "Item": {
           "id": {
               "N": $input.json("$.id")
           },
           "type": {
               "S": $input.json("$.type")
           },
           "price": {
               "N": $input.json("$.price")
           }
       }
   }

   This template specifies the table as data-transformation-tutorial-console-ddb and sets the items as id, type, and price. The items will come from the body of the POST method. You also can use a data model to help create a mapping template. For more information, see Use request validation in API Gateway.

7. Choose Save to save your mapping template.

To add a method and integration response from the POST method

The Amazon CloudFormation created a blank method and integration response. You will edit this response to provide more information. For more information about how to edit responses, see Amazon API Gateway API request and response data mapping reference.

1. On the Integration response tab, for Default - Response, choose Edit.

2. Choose Mapping templates, and then choose Add mapping template.

3. For Content-type, enter application/json.

4. In the code editor, enter the following output mapping template to send an output message:

   { "message" : "Your response was recorded at $context.requestTime" }

   For more information about context variables, see $context Variables for data models, authorizers, mapping templates, and CloudWatch access logging.

5. Choose Save to save your mapping template.

Test the POST method

Choose the Test tab. You might need to choose the right arrow button to show the tab.

1. In the request body, enter the following example.

   {
             "id": "4",
             "type" : "dog",
             "price": "321"
   }

2. Choose Test.

   The output should show your success message.

   You can open the DynamoDB console at https://console.amazonaws.cn/dynamodb/ to verify that the example item is in your table.

To delete an Amazon CloudFormation stack

1. Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

2. Select your Amazon CloudFormation stack.

3. Choose Delete and then confirm your choice.

To create an Amazon CloudFormation stack

Download and unzip the app creation template for Amazon CloudFormation.

To complete the following tutorial, you need the Amazon Command Line Interface (Amazon CLI) version 2.

For long commands, an escape character (\) is used to split a command over multiple lines.

1. Use the following command to create the Amazon CloudFormation stack.

   aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM 

2. Amazon CloudFormation provisions the resources specified in the template. It can take a few minutes to finish provisioning your resources. Use the following command to see the status of your Amazon CloudFormation stack.

   aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli

3. When the status of your Amazon CloudFormation stack is StackStatus: "CREATE_COMPLETE", use the following command to retrieve relevant output values for future steps.

    aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"

   The output values are the following:

   • ApiRole, which is the role name that allows API Gateway to put items in the DynamoDB table. For this tutorial, the role name is data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG.

   • DDBTableName, which is the name of the DynamoDB table. For this tutorial, the table name is data-transformation-tutorial-cli-ddb

   • ResourceId, which is the ID for the pets resource where the GET and POST methods are exposed. For this tutorial, the Resource ID is efg456

   • ApiId, which is the ID for the API. For this tutorial, the API ID is abc123.

To test the GET method before data transformation

• Use the following command to test the GET method.

  aws apigateway test-invoke-method --rest-api-id abc123 \
            --resource-id efg456 \
            --http-method GET

  The output of the test will show the following.

  [
    {
      "id": 1,
      "type": "dog",
      "price": 249.99
    },
    {
      "id": 2,
      "type": "cat",
      "price": 124.99
    },
    {
      "id": 3,
      "type": "fish",
      "price": 0.99
    }
  ]

  You will transform this output according to the mapping template in PetStore mapping template.

To transform the GET integration response

• Use the following command to update the integration response for the GET method. Replace the rest-api-id and resource-id with your values.

  Use the following command to create the integration response.

  aws apigateway put-integration-response --rest-api-id abc123 \
    --resource-id efg456 \
    --http-method GET \
    --status-code 200 \
    --selection-pattern "" \
    --response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n  \"description\": \"Item $elem.id is a $elem.type\",\n  \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'

To test the GET method

• Use the following command to test the GET method.

  aws apigateway test-invoke-method --rest-api-id abc123 \
    --resource-id efg456 \
    --http-method GET \
  

  The output of the test will show the transformed response.

  [
    {
      "description" : "Item 1 is a dog.",
      "askingPrice" : 249.99
    },
    {
      "description" : "Item 2 is a cat.",
      "askingPrice" : 124.99
    },
    {
      "description" : "Item 3 is a fish.",
      "askingPrice" : 0.99
    }
  ]

To create a POST method

1. Use the following command to create a new method on the /pets resource.

   aws apigateway put-method --rest-api-id abc123 \
     --resource-id efg456 \
     --http-method POST \
     --authorization-type "NONE" \
   

   This method will allow you to send pet information to the DynamoDB table that your created in the Amazon CloudFormation stack.

2. Use the following command to create an Amazon Web Service integration on the POST method.

   aws apigateway put-integration --rest-api-id abc123 \
     --resource-id efg456 \
     --http-method POST \
     --type AWS \
     --integration-http-method POST \
     --uri "arn:aws:apigateway:us-west-2:dynamodb:action/PutItem" \
     --credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
     --request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
   

3. Use the following command to create a method response for a successful call of the POST method.

   aws apigateway put-method-response --rest-api-id abc123 \
     --resource-id efg456 \
     --http-method POST \
     --status-code 200

4. Use the following command to create an integration response for the successful call of the POST method.

   aws apigateway put-integration-response --rest-api-id abc123 \
     --resource-id efg456 \
     --http-method POST \
     --status-code 200 \
     --selection-pattern "" \
     --response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'

To test the POST method

• Use the following command to test the POST method.

  aws apigateway test-invoke-method --rest-api-id abc123 \
    --resource-id efg456 \
    --http-method POST \
    --body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'

  The output will show the successful message.

To delete an Amazon CloudFormation stack

• Use the following command to delete your Amazon CloudFormation resources.

  aws cloudformation delete-stack  --stack-name data-transformation-tutorial-cli