Read the Metadata Back with a Simple API

Learning Outcomes

By the end of this lesson, you will be able to:

1. Build a simple HTTP API that reads metadata from DynamoDB.
2. Explain why API Gateway + Lambda is a good pattern for exposing data over HTTP.
3. Read query parameters from an API request and use them to fetch a DynamoDB item.
4. Return JSON from Lambda in a format API Gateway can send back to the client.
5. Test the endpoint with a real request and understand the response.

---

The Core Idea

You already have a pipeline that stores upload metadata in DynamoDB. Now you need a way to read it back.

A clean pattern is:

• API Gateway HTTP API receives the request
• Lambda processes the request
• DynamoDB returns the metadata item

---

Why use API Gateway instead of just a Lambda Function URL?

AWS documents two ways to expose Lambda over HTTP: API Gateway and Lambda function URLs. Function URLs are simpler, but API Gateway is the more standard path when you want routes, API structure, and room to grow.

For this lesson, use API Gateway HTTP API because:

• It matches common real-world serverless architecture.
• It gives you a clean route like /metadata.
• It prepares you for later lessons with multiple routes and methods.

---

What You Will Build

You will create:

• One new Lambda function for reads
• One API Gateway HTTP API
• One GET /metadata route
• One Lambda integration
• One test request like: GET /metadata?bucket=your-bucket-name&key=incoming/notes.txt

---

Part 1: Create the Read Lambda Function

Create a new Lambda function in the same Region as your DynamoDB table. Set one environment variable: TABLE_NAME=upload_metadata.

Use this Python code:

import json
import os
import boto3

dynamodb = boto3.resource("dynamodb")
table = dynamodb.Table(os.environ["TABLE_NAME"])

def lambda_handler(event, context):
    query = event.get("queryStringParameters") or {}

    bucket = query.get("bucket")
    object_key = query.get("key")

    if not bucket or not object_key:
        return {
            "statusCode": 400,
            "headers": {"Content-Type": "application/json"},
            "body": json.dumps({
                "error": "Missing required query parameters: bucket and key"
            })
        }

    response = table.get_item(
        Key={
            "bucket": bucket,
            "object_key": object_key
        }
    )

    item = response.get("Item")

    if not item:
        return {
            "statusCode": 404,
            "headers": {"Content-Type": "application/json"},
            "body": json.dumps({
                "error": "Metadata not found"
            })
        }

    return {
        "statusCode": 200,
        "headers": {"Content-Type": "application/json"},
        "body": json.dumps(item)
    }

---

Part 2: Give the Lambda Function Permission to Read DynamoDB

This function needs dynamodb:GetItem permission on the upload_metadata table. A minimal policy looks like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadMetadataFromDynamoDB",
      "Effect": "Allow",
      "Action": ["dynamodb:GetItem"],
      "Resource": "arn:aws:dynamodb:REGION:ACCOUNT_ID:table/upload_metadata"
    },
    {
      "Sid": "WriteLogs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

---

Part 3: Create the HTTP API

Create an API Gateway HTTP API. Then:

1. Create a route: GET /metadata
2. Add a Lambda integration pointing to your read function
3. Deploy the API

---

Part 4: Understand the Event coming from API Gateway

With Lambda proxy integration, API Gateway passes request data (headers, query parameters, etc.) to the Lambda event object. For this lesson, the part you care about is event.get("queryStringParameters").

---

Part 5: Test the API

Once deployed, API Gateway gives you an invoke URL. Your test request should look like: https://YOUR_API_ID.execute-api.YOUR_REGION.amazonaws.com/metadata?bucket=YOUR_BUCKET&key=incoming/notes.txt

Expected Responses

Success (200 OK)

{
  "bucket": "my-upload-bucket",
  "object_key": "incoming/notes.txt",
  "size": 42,
  "etag": "abc123...",
  "event_time": "2026-03-09T18:00:00.000Z",
  "event_name": "ObjectCreated:Put",
  "sequencer": "0065..."
}

Not Found (404)

{
  "error": "Metadata not found"
}

---

Lab Checklist

---

Micro-activity 1: Test Response Review

---

Micro-activity 2: Match the API Flow

---

Summary

In this lesson, you turned your metadata pipeline into a simple read API. API Gateway HTTP API received a request, Lambda parsed the query parameters, DynamoDB returned the matching item, and Lambda returned JSON to the client.

---

Quiz