AwsHow-ToBeginner · 4 min read

How to Use DynamoDB with API Gateway: Simple Integration Guide

You can use API Gateway to create RESTful endpoints that directly interact with DynamoDB using AWS service integrations. This setup allows you to perform database operations like GetItem or PutItem through HTTP requests without writing backend code.

📐

Syntax

API Gateway integrates with DynamoDB using AWS Service Proxy. You define a Method in API Gateway with an Integration Request that calls DynamoDB actions like GetItem or PutItem. The request and response are mapped using Mapping Templates in Velocity Template Language (VTL).

Key parts:

HTTP Method: Usually POST for DynamoDB actions.
Integration Type: AWS Service.
Action: DynamoDB API operation (e.g., GetItem).
Request Mapping Template: Converts HTTP request to DynamoDB JSON format.
Response Mapping Template: Converts DynamoDB response back to HTTP JSON.

plaintext

POST /items
Integration Type: AWS Service
AWS Service: dynamodb
AWS Region: your-region
Action: GetItem or PutItem
Request Mapping Template (example for GetItem):
{
  "TableName": "YourTable",
  "Key": {
    "id": {"S": "$input.path('$.id')"}
  }
}
Response Mapping Template:
$input.path('$')

💻

Example

This example shows how to create an API Gateway POST method that writes an item to DynamoDB using PutItem. The request body contains JSON with an id and name. The integration request maps this to DynamoDB format, and the response returns success status.

json

{
  "swagger": "2.0",
  "info": {
    "title": "DynamoDB API",
    "version": "1.0"
  },
  "paths": {
    "/items": {
      "post": {
        "x-amazon-apigateway-integration": {
          "uri": "arn:aws:apigateway:us-east-1:dynamodb:action/PutItem",
          "httpMethod": "POST",
          "type": "aws",
          "credentials": "arn:aws:iam::123456789012:role/apigateway-dynamodb-role",
          "requestTemplates": {
            "application/json": "{\n  \"TableName\": \"YourTable\",\n  \"Item\": {\n    \"id\": {\"S\": \"$input.path('$.id')\"},\n    \"name\": {\"S\": \"$input.path('$.name')\"}\n  }\n}"
          },
          "responses": {
            "default": {
              "statusCode": "200",
              "responseTemplates": {
                "application/json": "{ \"message\": \"Item added successfully\" }"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  }
}

Output

{"message": "Item added successfully"}

⚠️

Common Pitfalls

Common mistakes when integrating API Gateway with DynamoDB include:

Not setting correct IAM role permissions for API Gateway to access DynamoDB.
Incorrect request mapping templates causing DynamoDB to receive malformed JSON.
Using GET method instead of POST for DynamoDB actions which require POST.
Not handling response mapping, leading to confusing client responses.

Example of a wrong request template missing DynamoDB JSON format:

plaintext

Wrong request template:
{
  "id": "$input.path('$.id')"
}

Right request template:
{
  "TableName": "YourTable",
  "Key": {
    "id": {"S": "$input.path('$.id')"}
  }
}

📊

Quick Reference

Integration Type: AWS Service
HTTP Method: POST
DynamoDB Actions: GetItem, PutItem, UpdateItem, DeleteItem
Request Mapping: Convert HTTP JSON to DynamoDB JSON format
Response Mapping: Convert DynamoDB JSON to HTTP JSON
IAM Role: API Gateway needs permission to call DynamoDB

✅

Key Takeaways

Use API Gateway AWS Service Proxy integration with POST method to call DynamoDB actions.

Always map HTTP request and response bodies correctly using mapping templates.

Ensure API Gateway has an IAM role with permissions to access DynamoDB.

Use DynamoDB JSON format in request templates to avoid errors.

Test your API with sample requests to verify integration works as expected.