DEV Community: Gloria

Automated Integration Tests for the Deployed Hello World API

Gloria — Thu, 17 Sep 2026 16:19:35 +0000

In Part 1, we built our Hello World API and got it running locally. But writing code is only half the story — you also need to know it actually works, both before and after it leaves your machine.

In this part, we will pick up where we left off. We will run local integration tests to catch issues early, deploy the API to AWS, verify the live deployment by hand with a browser and curl, and then add automated integration tests against the real deployed stack — so you are never relying on manual checks alone.

Along the way, I share a few challenges I hit and how I worked through them, before wrapping up with final takeaways.

By the end, you will have a full picture of the workflow across three stages — local integration testing, manual verification of the deployed API, and automated integration testing against the live AWS stack. There is also a hands-on challenge at the end:

-Add a new /goodbye endpoint yourself and push it through all three test layers, from unit test to live deployment. That is your chance to practice the full workflow, not just read about it.

TL;DR — What We Built in Part 1

In Part 1 we built a serverless REST API from scratch using AWS SAM, Python 3.11, and API Gateway. Here is what we shipped:

A template.yaml that defines all infrastructure as code — API Gateway, Lambda function, three routes, CORS, throttling, and CloudWatch metrics
A Lambda function (app.py) with three endpoints: GET /, GET /hello, and GET /get-documentation
15 unit tests using pytest that call Lambda directly — no network, no Docker, no AWS The unit tests all passed in 0.16 seconds. But, here is the question:

If your unit tests all pass, does that mean your API actually works?

Not necessarily. And Part 2 is the answer.

Introduction — What Part 2 Covers

Unit tests call your Lambda function directly in Python. They bypass API Gateway entirely. They never touch a network. They never check whether your template.yaml wires the routes correctly, or whether the deployed stack responds the way a real client expects.

Integration tests fix that. They go through the real path a request takes:

Client → API Gateway → Lambda → API Gateway → Client

In this article you will:

✅ Understand what integration testing is and why unit tests are not enough
✅ Learn the 2 types of integration tests this project implements
✅ Write and run local integration tests against sam local start-api
✅ Deploy the API to AWS and manually verify all endpoints
✅ Write and run deployed integration tests against your real AWS stack
✅ Challenges and lessons learned
✅ Hands-on challenge

What Is Integration Testing?

A unit test checks one small piece of your code in isolation. It calls a single function, passes in a fake input, and checks the output. Fast. No network. No infrastructure.

An integration test checks how multiple pieces work together. For a serverless API, that means:

Does API Gateway route the request to the right Lambda function?
Do the CORS headers actually arrive at a real HTTP client?
What does a client receive when they hit a path that does not exist?
Does the deployed stack behave the same as the local simulation? These questions cannot be answered by calling lambda_handler() directly. You need a real HTTP request going through the full stack.

Unit tests prove your logic. Integration tests prove your wiring. Both are necessary. Neither replaces the other.

The 2 Types of Integration Tests This Project Implements

This project implements integration testing at two levels, in a deliberate order:

Type 1 — Local integration tests

Target: sam local start-api running on localhost:3000

SAM runs a Docker container that simulates Lambda locally and routes requests through a local API Gateway. Your tests hit localhost:3000 over real HTTP — no mocking, no shortcuts — but nothing leaves your machine and you pay nothing.

Running these tests before deploying catches wiring problems early and gives you fast feedback.

Type 2 — Deployed integration tests

Target: your real AWS stack after sam deploy

These tests fetch the live API Gateway URL from CloudFormation and send real HTTP requests to your deployed Lambda function in AWS. This is as close as you can get to what a real user experiences.

Run these after deploying. They confirm your real AWS infrastructure works end-to-end.

	Local integration	Deployed integration
Target	`localhost:3000`	Real AWS URL
Docker needed	Yes	No
AWS account needed	No	Yes
Cost	Free	Tiny (pay-per-request Lambda)
What it catches	SAM wiring, routing, local behaviour	Real deployment, real latency, real API Gateway

Prerequisites

You need everything from Part 1, plus:

requests installed: python -m pip install requests
boto3 installed: python -m pip install boto3

Note: Use python -m pip install instead of just pip install. This guarantees you are installing into the same Python environment that pytest uses. Using plain pip can silently install into a different environment — your tests will then fail with ModuleNotFoundError even though you think the package is installed.

Part 1: Local Integration Tests

Step 1: Create the Integration Test Folder

Your unit tests live in tests/unit/. Integration tests get their own folder so you can run each layer independently:

mkdir hello-world-api/tests/integration
touch hello-world-api/tests/integration/__init__.py
touch hello-world-api/tests/integration/test_api_gateway_local.py

Your folder structure should now look like this:

hello-world-api/
├── hello_world/
│   └── app.py
├── template.yaml
└── tests/
    ├── __init__.py
    ├── unit/
    │   ├── __init__.py
    │   └── test_app.py
    └── integration/
        ├── __init__.py
        └── test_api_gateway_local.py   ← we are building this now

Step 2: Write the Local Integration Tests

Open tests/integration/test_api_gateway_local.py and paste in the following:

import requests

BASE_URL = "http://localhost:3000"


def test_hello_default_name():
    response = requests.get(f"{BASE_URL}/hello")
    assert response.status_code == 200
    body = response.json()
    assert body["message"] == "Hello, World!"


def test_hello_with_name_param():
    response = requests.get(f"{BASE_URL}/hello", params={"name": "Gloria"})
    assert response.status_code == 200
    assert response.json()["message"] == "Hello, Gloria!"


def test_hello_response_headers():
    response = requests.get(f"{BASE_URL}/hello")
    assert response.headers["Content-Type"] == "application/json"
    assert response.headers["Access-Control-Allow-Origin"] == "*"


def test_documentation_endpoint_returns_html():
    response = requests.get(f"{BASE_URL}/get-documentation")
    assert response.status_code == 200
    assert response.headers["Content-Type"] == "text/html"
    assert "Hello API" in response.text


def test_unknown_path_returns_404():
    response = requests.get(f"{BASE_URL}/does-not-exist")
    assert response.status_code == 404
    assert response.json()["error"] == "Endpoint not found"


def test_post_request_rejected_by_api_gateway():
    response = requests.post(f"{BASE_URL}/hello")
    # API Gateway itself rejects this — your Lambda never runs
    assert response.status_code == 403

Understanding the Test Code

No mocking. Compare this to your unit tests — there is no mock_event() helper anywhere. There is nothing to mock. The request really travels over localhost:3000, through SAM's local API Gateway simulation, into a Docker container running your Lambda function, and back.

BASE_URL = "http://localhost:3000" is hardcoded. This is intentional for local tests because SAM Local runs the API on localhost:3000 by default, so using a constant keeps the test simple and easy to understand. When we move to deployed tests, the URL lives in AWS — not on your machine. Rather than hardcoding it, boto3 fetches it directly from CloudFormation, and the fixture delivers it to every test that needs it.

These tests will fail with a ConnectionRefusedError if sam local start-api is not running. That is a feature, not a bug — it forces you to actually start the local API before the tests run, rather than silently testing nothing.

The six tests and what each one proves:
- test_hello_default_name — sends GET /hello with no parameters and checks that the response is 200 and the message is "Hello, World!". This confirms the default name fallback works end-to-end through API Gateway, not just inside Lambda.
- test_hello_with_name_param — sends GET /hello?name=Gloria and checks that the message becomes "Hello, Gloria!". This confirms query parameter extraction works through the full request path, not just in the unit test mock.
- test_hello_response_headers — checks that Content-Type: application/json and Access-Control-Allow-Origin: * actually arrive at the HTTP client. Your unit tests could assert these headers exist in Lambda's return value, but only an integration test confirms they survive the trip through API Gateway and arrive in the real HTTP response.
- test_documentation_endpoint_returns_html — sends GET /get-documentation and checks that the response is 200, the Content-Type is text/html, and the word "Hello API" appears in the body. This confirms Lambda can serve HTML through API Gateway, not just JSON.
- test_unknown_path_returns_404 — sends GET /does-not-exist and checks for 404 status code and "Endpoint not found" in the error body. This feels natural coming from the unit tests — Lambda returns 404 for unknown paths, so 404 is what you expect. Write it this way first. It will fail, and that failure is the lesson. The full story is in the next section.
- test_post_request_rejected_by_api_gateway — sends POST /hello and checks for 403. Only GET is configured in template.yaml, so API Gateway rejects the POST before Lambda runs. A unit test calling lambda_handler() directly would never see this 403 because Lambda was never invoked.

Step 3: Run the Local Integration Tests

You need two terminals open at the same time.

Terminal 1 — start the local API:

sam local start-api

Wait until you see:

Mounting HelloWorldFunction at http://127.0.0.1:3000/ [GET]
Mounting HelloWorldFunction at http://127.0.0.1:3000/get-documentation [GET]
Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]
You can now browse to the above endpoints to invoke your functions.

Terminal 2 — run the tests:

python -m pytest tests/integration/test_api_gateway_local.py -v

What You Should See — and One Surprise

tests/integration/test_api_gateway_local.py::test_hello_default_name PASSED [ 16%]
tests/integration/test_api_gateway_local.py::test_hello_with_name_param PASSED [ 33%]
tests/integration/test_api_gateway_local.py::test_hello_response_headers PASSED [ 50%]
tests/integration/test_api_gateway_local.py::test_documentation_endpoint_returns_html PASSED [ 66%]
tests/integration/test_api_gateway_local.py::test_unknown_path_returns_404 FAILED [ 83%]
tests/integration/test_api_gateway_local.py::test_post_request_rejected_by_api_gateway PASSED [100%]

1 failed, 5 passed in 11.73s

One test failed. Here is the full error:

 ================================== FAILURES ===================================
________________________ test_unknown_path_returns_404 ________________________

    def test_unknown_path_returns_404():
        response = requests.get(f"{BASE_URL}/does-not-exist")
>       assert response.status_code == 404
E       assert 403 == 404
E        +  where 403 = <Response [403]>.status_code

tests\integration\test_api_gateway_local.py:34: AssertionError
=========================== short test summary info ===========================
FAILED tests/integration/test_api_gateway_local.py::test_unknown_path_returns_404

Discovery #1: Why 403 and Not 404?

Your first instinct might be to think you broke something. You did not. This is API Gateway teaching you something a unit test never could.

Here is what actually happens when you request /does-not-exist:

The request hits API Gateway first.
API Gateway checks template.yaml for a matching route.
No matching route exists.
API Gateway rejects the request itself, with 403 Missing Authentication Token.
Lambda never runs. Compare that to your unit test, which calls lambda_handler() directly — skipping API Gateway entirely. Lambda runs, hits return error_response(404, "Endpoint not found"), and returns a clean 404. That is correct Lambda behaviour. It is just not what a real client ever sees.

This gap — between what your code does and what a client actually receives — is exactly what integration tests are for. Unit tests cannot catch it, because they never involve API Gateway at all.

The fix — update the test to match the real behaviour:

def test_unknown_path_returns_403():
    response = requests.get(f"{BASE_URL}/does-not-exist")
    assert response.status_code == 403
    assert response.json() == {"message": "Missing Authentication Token"}

Run again after the fix:

6 passed in 10.54s

The unit test still correctly asserts 404 — that is Lambda's behaviour when called directly. This integration test correctly asserts 403 — that is API Gateway's behaviour when a real request goes through the full stack. Both are right. They are just testing different layers.

In this API, 403 Missing Authentication Token on an unknown path means API Gateway could not match the request to a configured resource or method. It does not mean Lambda rejected the request or that your Lambda execution role lacks permission.

Remember this: whenever you see 403 Missing Authentication Token from API Gateway, check the route and HTTP method before assuming you have an IAM problem.

Part 2: Deploy the API to AWS

Before we can run deployed integration tests, we need a deployed stack.

Step 1: Build and Deploy

sam build
sam deploy --guided

Follow the prompts. When asked for the stack name, enter hello-world-api. Accept the defaults for everything else.

Setting default arguments for 'sam deploy'
Stack Name [sam-app]: hello-world-api
AWS Region [us-east-1]:
#Shows you resources changes to be deployed and require a 'Y' to initiate deploy
Confirm changes before deploy [y/N]: y
#SAM needs permission to be able to create roles to connect to the resources in your template
Allow SAM CLI IAM role creation [Y/n]:
#Preserves the state of previously provisioned resources when an operation fails
Disable rollback [y/N]:
HelloWorldFunction has no authentication. Is this okay? [y/N]: y
HelloWorldFunction has no authentication. Is this okay? [y/N]: y
HelloWorldFunction has no authentication. Is this okay? [y/N]: y
Save arguments to configuration file [Y/n]: y
SAM configuration file [samconfig.toml]:
SAM configuration environment [default]:

At the end of a successful deployment, CloudFormation prints your stack outputs:

CloudFormation outputs from deployed stack
---------------------------------------------------------------------------
Key                 HelloApiUrl
Description         Hello endpoint
Value               https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/hello

Key                 RootUrl
Description         Root URL - serves documentation page
Value               https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/

Key                 DocumentationUrl
Description         Documentation endpoint
Value               https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/get-documentation
--------------------------------------------------------------------------

Note: The string azmimofsv1 in the URL is your API Gateway ID. AWS generates it randomly — yours will be different. Replace it with your own ID in all the commands below.

Part 3: Manually Test the Deployed API Endpoints

Before running any automated tests, verify the deployed endpoints are alive and responding correctly. Do not trust automation to confirm something works until you have seen it work yourself, at least once.

Test Using the Browser

Test GET /hello — default greeting:

Paste your HelloApiUrl into the browser address bar. You should see:

{
  "message": "Hello, World!",
  "timestamp": "2026-06-20T22:48:21.123456+00:00",
  "method": "GET",
  "path": "/hello",
  "version": "1.0"
}

Test GET /hello with a name parameter:

Add ?name=YourName to the URL:

https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/hello?name=Gloria

You should see:

{
  "message": "Hello, Gloria!",
  "timestamp": "2026-09-01T11:58:58.392697+00:00",
  "method": "GET",
  "path": "/hello",
  "version": "1.0"
}

Test GET /get-documentation:

Paste your DocumentationUrl into a new browser tab:

https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/get-documentation

You should see the styled HTML documentation page served directly from AWS Lambda.

Test GET / — root endpoint:

Paste your RootUrl into a new tab:

https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/

This should also render the documentation page.

Using curl

# Test /hello
curl https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/hello

# Test /hello with name
curl https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/hello?name=Gloria

# Test /get-documentation
curl https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/get-documentation

# Test root
curl https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/

Test non-GET methods — should be blocked by API Gateway:

# POST — should return 403
curl -X POST https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/hello

# PUT — should return 403
curl -X PUT https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/hello

Test an unknown path:

curl https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/does-not-exist

You should see {"message": "Missing Authentication Token"} with a 403 status code. Your Lambda never ran. This is the same 403 behaviour you discovered during local integration testing — now confirmed against the real deployed stack.

All four GET endpoints responding correctly. Good. Now we automate all of this.

Part 4: Automated Integration Tests for the Deployed Hello World API

Step 1: Create the Deployed Integration Test File

touch hello-world-api/tests/integration/test_api_gateway_deployed.py

Your folder structure should now look like this:

hello-world-api/
├── hello_world/
│   └── app.py
├── template.yaml
└── tests/
    ├── __init__.py
    ├── unit/
    │   ├── __init__.py
    │   └── test_app.py
    └── integration/
        ├── __init__.py
        ├── test_api_gateway_local.py
        └── test_api_gateway_deployed.py  ← we are building this now

Step 2: Write the Deployed Integration Tests

Open tests/integration/test_api_gateway_deployed.py and paste in the following code:

import os
import boto3
import pytest
import requests

"""
Make sure env variable AWS_SAM_STACK_NAME exists with the name of the stack we are going to test.
Run this before pytest:
    export AWS_SAM_STACK_NAME=hello-world-api
"""


# ── fixtures ──────────────────────────────────────────────────────────────────

@pytest.fixture()
def stack_urls():
    """Fetch all API URLs from the deployed CloudFormation stack outputs."""
    stack_name = os.environ.get("AWS_SAM_STACK_NAME")

    if stack_name is None:
        raise ValueError(
            "Please set the AWS_SAM_STACK_NAME environment variable.\n"
            "Run: export AWS_SAM_STACK_NAME=hello-world-api"
        )

    client = boto3.client("cloudformation")

    try:
        response = client.describe_stacks(StackName=stack_name)
    except Exception as e:
        raise Exception(
            f"Cannot find stack '{stack_name}'.\n"
            f"Make sure you have run 'sam deploy' before running these tests."
        ) from e

    outputs = response["Stacks"][0]["Outputs"]

    # Build a dictionary of all stack outputs keyed by OutputKey
    url_map = {item["OutputKey"]: item["OutputValue"] for item in outputs}

    # Confirm the keys we need are actually present
    required_keys = ["HelloApiUrl", "DocumentationUrl", "RootUrl"]
    for key in required_keys:
        if key not in url_map:
            raise KeyError(f"Expected output key '{key}' not found in stack '{stack_name}'")

    return url_map



# ── tests ─────────────────────────────────────────────────────────────────────

def test_hello_default_name(stack_urls):
    response = requests.get(stack_urls["HelloApiUrl"])
    assert response.status_code == 200
    body = response.json()
    assert body["message"] == "Hello, World!"
    assert body["version"] == "1.0"


def test_hello_with_name_param(stack_urls):
    response = requests.get(stack_urls["HelloApiUrl"], params={"name": "Gloria"})
    assert response.status_code == 200
    assert response.json()["message"] == "Hello, Gloria!"


def test_hello_response_headers(stack_urls):
    response = requests.get(stack_urls["HelloApiUrl"])
    assert "application/json" in response.headers["Content-Type"]
    assert response.headers["Access-Control-Allow-Origin"] == "*"


def test_documentation_endpoint_returns_html(stack_urls):
    response = requests.get(stack_urls["DocumentationUrl"])
    assert response.status_code == 200
    assert "text/html" in response.headers["Content-Type"]
    assert "Hello API" in response.text


def test_root_endpoint_returns_html(stack_urls):
    response = requests.get(stack_urls["RootUrl"])
    assert response.status_code == 200
    assert "text/html" in response.headers["Content-Type"]


def test_unknown_path_returns_403(stack_urls):
    # Extract base URL from HelloApiUrl
    # HelloApiUrl = https://xxx.execute-api.us-east-1.amazonaws.com/Prod/hello
    # Base URL    = https://xxx.execute-api.us-east-1.amazonaws.com/Prod
    base_url = stack_urls["HelloApiUrl"].rsplit("/hello", 1)[0]
    response = requests.get(f"{base_url}/does-not-exist")
    # API Gateway returns 403 for unknown paths — Lambda is never invoked
    assert response.status_code == 403


def test_post_request_rejected(stack_urls):
    response = requests.post(stack_urls["HelloApiUrl"])
    # API Gateway rejects POST — Lambda is never invoked
    assert response.status_code == 403

Understanding the Test Code

The file has two parts: one fixture that uses boto3 to fetch the URLs from CloudFormation and delivers them to the tests, and seven tests that use them.

Imports and the environment variable

import os
import boto3
import pytest
import requests

os: reads the shell environment variable.
boto3: talks to AWS.
requests: makes the HTTP calls.
pytest: provides the fixture system.
Fixtures
The first thing the fixture does is read your stack name from the shell:

stack_name = os.environ.get("AWS_SAM_STACK_NAME")

if stack_name is None:
    raise ValueError(
        "Please set the AWS_SAM_STACK_NAME environment variable.
"
        "Run: export AWS_SAM_STACK_NAME=hello-world-api"
    )

The stack name is not hardcoded in the file. It lives in a shell environment variable you set before running the tests. This keeps it out of your code so the same test file works for any stack name, any environment. The if stack_name is None check gives you a clear, actionable error if you forget to set it, instead of a confusing boto3 exception later.

The @pytest.fixture() decorator

@pytest.fixture()
def stack_urls():

This decorator transforms stack_urls from a plain function into a pytest fixture — a piece of setup code that pytest runs automatically and injects into any test that lists stack_urls as a parameter. Pytest sees the parameter name in a test, finds the matching fixture, runs it, and passes the return value in.

The reason this is a fixture rather than a constant like BASE_URL = "http://localhost:3000" is that we do not want to hardcode environment-specific AWS URLs into our tests. The API Gateway URL is tied to the deployed API and stage, and we can retrieve the current value directly from CloudFormation. This makes the tests portable across environments and avoids manually updating URLs if the stack configuration changes.

boto3 fetches the URL from CloudFormation

client = boto3.client("cloudformation")

try:
    response = client.describe_stacks(StackName=stack_name)
except Exception as e:
    raise Exception(
        f"Cannot find stack '{stack_name}'.
"
        f"Make sure you have run 'sam deploy' before running these tests."
    ) from e

When sam deploy completes, CloudFormation stores your stack output values — including all three API URLs you defined in template.yaml. boto3 reads those outputs here with describe_stacks.

The try/except block gives you a clear error message if the stack does not exist yet — which happens if you run the tests before deploying. Without it, you would get a raw boto3 exception that does not tell you what to do next.
Building the dictionary

outputs = response["Stacks"][0]["Outputs"]

url_map = {item["OutputKey"]: item["OutputValue"] for item in outputs}

required_keys = ["HelloApiUrl", "DocumentationUrl", "RootUrl"]
for key in required_keys:
    if key not in url_map:
        raise KeyError(f"Expected output key '{key}' not found in stack '{stack_name}'")

return url_map

outputs is a list of dictionaries from CloudFormation — one per output key. The list comprehension converts it into a single flat dictionary:

{
    "HelloApiUrl": "https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/hello",
    "DocumentationUrl": "https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/get-documentation",
    "RootUrl": "https://azmimofsv1.execute-api.us-east-1.amazonaws.com/Prod/",
    "HelloWorldFunctionArn": "arn:aws:lambda:...",
    "HelloWorldFunctionIamRole": "arn:aws:iam:..."
}

The fixture returns this whole dictionary rather than a single URL. The required_keys check fails fast with a clear message if your stack is missing an expected output key.

The seven tests
Every test receives stack_urls as a parameter and uses it to get the URL it needs.
- test_hello_default_name — sends GET /hello with no parameters and checks that the status is 200, the message is "Hello, World!", and the version is "1.0". This confirms the full deployed stack — API Gateway, Lambda, routing, and response formatting — is wired correctly end to end.
- test_hello_with_name_param — sends GET /hello?name=Gloria and checks that the message becomes "Hello, Gloria!". This confirms query parameter extraction works through the real deployed API Gateway, not just locally.
- test_hello_response_headers — checks that Content-Type contains application/json and Access-Control-Allow-Origin is *. Notice the assertion uses in instead of == for Content-Type. The deployed API Gateway adds charset=utf-8 — returning application/json; charset=utf-8 — that sam local does not. Using in means this test passes in both environments without any changes.
- test_documentation_endpoint_returns_html — sends GET /get-documentation and checks for 200, text/html content type, and "Hello API" in the body. This confirms the HTML documentation endpoint works in the real deployed stack, served from Lambda through API Gateway.
- test_root_endpoint_returns_html — sends GET / and checks for 200 and text/html. This confirms the root endpoint is correctly routed to the same documentation handler as /get-documentation.
- test_unknown_path_returns_403 — there is no BaseUrl output key in your CloudFormation stack, so the test derives the base URL by stripping /hello from the end of HelloApiUrl:

base_url = stack_urls["HelloApiUrl"].rsplit("/hello", 1)[0]
response = requests.get(f"{base_url}/does-not-exist")
assert response.status_code == 403

This is a small but deliberate choice — rather than adding another output to template.yaml, you compute what you need from what you already have.

test_post_request_rejected — sends POST /hello and checks for 403. Confirms that the deployed API Gateway rejects non-GET methods the same way the local simulation does. Lambda is never invoked.

Step 3: Set the Environment Variable

The test reads your stack name from a shell environment variable — not from a file inside your project. This keeps your stack name out of your code, meaning the same test file works for any environment by changing one variable.

export AWS_SAM_STACK_NAME=hello-world-api

Note: This variable lives in your terminal session only. It disappears when you close the terminal. Set it again each time you open a new session before running deployed tests.

Step 4: Run the Deployed Integration Tests

python -m pytest tests/integration/test_api_gateway_deployed.py -v

What You Should See

tests/integration/test_api_gateway_deployed.py::test_hello_default_name PASSED
tests/integration/test_api_gateway_deployed.py::test_hello_with_name_param PASSED
tests/integration/test_api_gateway_deployed.py::test_hello_response_headers PASSED
tests/integration/test_api_gateway_deployed.py::test_documentation_endpoint_returns_html PASSED
tests/integration/test_api_gateway_deployed.py::test_root_endpoint_returns_html PASSED
tests/integration/test_api_gateway_deployed.py::test_unknown_path_returns_403 PASSED
tests/integration/test_api_gateway_deployed.py::test_post_request_rejected PASSED

7 passed in 21.25s

7 passed means your deployed stack is healthy.

Why 21 Seconds?

Your local integration tests ran in 11 seconds. Your deployed tests took 21 seconds. The difference comes from testing real infrastructure across the network, plus the additional processing involved in API Gateway and Lambda. That extra time is expected.

Discovery #2 — Empty Query Parameter Bug

Seven tests passed. I was almost ready to publish. Then I tested one more edge case.

I sent this request to the deployed API:

/hello?name=

The response came back as:

{"message": "Hello, !", "timestamp": "2026-09-15T22:17:33.974145+00:00", "method": "GET", "path": "/hello", "version": "1.0"}

"Hello, !" — the name is empty. The intended behaviour was "Hello, World!".

Could a unit test have caught this? Yes. If we had written a unit test for the specific case of an empty string, it could have caught the bug. The problem was not that unit testing was incapable of finding it. We simply had not thought to test this edge case. The deployed integration test gave me another opportunity to discover it because I was testing the API with a real HTTP request and real query-string input — like what happens when a user sends ?name= with nothing after the equals sign.

This is a real application bug, not an infrastructure problem. And I only found it because I was testing edge cases before publishing.

Why It Happened

The original Lambda code uses:

name = query_params.get("name", "World")

This only falls back to "World" when the name key is completely absent from the query parameters. It handles:

/hello — no name key → falls back to "World" ✅

But it does not handle:

/hello?name= — name key exists, value is an empty string → returns "" ❌

The key is present in the dictionary, so .get() returns the empty string instead of the default.

The Fix — Adding a Regression Test

Step 1: First, write a test that exposes the bug:

def test_hello_with_empty_name(stack_urls):
    response = requests.get(
        stack_urls["HelloApiUrl"],
        params={"name": ""}
    )
    assert response.status_code == 200
    assert response.json()["message"] == "Hello, World!"

Step 2: Run it — it fails. That is the bug confirmed.

Step 3: Update the Lambda handler. Change:

name = query_params.get("name", "World")

To:

name = query_params.get("name") or "World"

The or operator returns "World" when name is either absent (None) or an empty string (""). Both cases now fall back to the default correctly.

Step 4: Add the regression test above to your deployed integration test file.

Step 5: Redeploy with sam build and sam deploy.

Step 6: Run the full test suite again and confirm all tests pass.

Once you apply the fix, keep this test in your suite permanently. It is now a regression test — its job is to make sure this specific bug never comes back. If someone later changes the Lambda handler and accidentally reintroduces the old query_params.get("name", "World") behaviour, this test fails immediately and catches it before it ships. Every bug you fix is an opportunity to write a regression test. Over time, your test suite becomes a record of every mistake you caught and fixed.

That is the real workflow in practice:

Discover
   ↓
Write a failing test
   ↓
Fix the code
   ↓
Deploy
   ↓
Run the tests
   ↓
Confirm everything passes

What this discovery taught me: integration testing does not just verify infrastructure. It can also expose application behaviour bugs when we exercise the system with realistic inputs. This bug could have been caught by a unit test, but my existing unit tests did not include the empty-string case. Testing the deployed API with realistic inputs exposed application behaviour bugs that I did not think to cover in my original automated tests.

That is one of the reasons I now see testing as more than simply checking whether the code works. Different tests give you different opportunities to discover problems:

Unit tests verify individual pieces of application logic.
Local integration tests verify how those pieces work together through the local HTTP interface.
Deployed integration tests exercise the application through the real API Gateway, Lambda, and AWS infrastructure.
Manual verification gives you another opportunity to try realistic requests and edge cases before publishing. > The goal is not to choose one type of test. It is to build enough layers of testing that a bug has fewer places to hide.

Running All Three Layers Together

You now have all three test layers. Here is how to run each one:

# Unit tests — fastest, no Docker, no AWS needed
python -m pytest tests/unit/ -v

# Local integration — Docker needed, sam local start-api must be running
python -m pytest tests/integration/test_api_gateway_local.py -v

# Deployed integration — AWS deployment needed, set env variable first
export AWS_SAM_STACK_NAME=hello-world-api
python -m pytest tests/integration/test_api_gateway_deployed.py -v

Your complete results across all layers:

tests/unit/test_app.py                                  15 passed    0.16s
tests/integration/test_api_gateway_local.py              6 passed   11.53s
tests/integration/test_api_gateway_deployed.py           7 passed   21.25s

28 passed

28 tests across three layers!

If you followed Discovery #2 and applied the fix, your test counts will differ from the ones shown above. To properly cover the fix, you would add an empty-name test to your deployed integration test file, a matching test to your local integration test file, and a unit test for the fixed behaviour. This bring the totals to 16 unit tests, 7 local integration tests, and 8 deployed integration tests, for a total of 31 passing tests. That is a good thing. Every bug you find and add a test for makes your test suite stronger. Real test suites grow as you discover and fix real bugs. That is exactly what happened here.

Challenges

The 403 vs 404 mismatch This one was subtler. My unit tests returned 404 for unknown paths, my integration tests returned 403 for unknown path, and both were "correct" — just testing different layers. The real lesson: API Gateway rejects unmatched routes before Lambda ever runs, so a unit test that calls lambda_handler() directly can never see that behavior. If you hit this, don't assume your code is broken — check whether the layer you're testing even reaches API Gateway or not.
The empty-string edge case Seven tests passed, and I was ready to publish but, then I tried /hello?name= just to be sure, and got back "Hello, !" instead of "Hello, World!". The bug was one line: query_params.get("name", "World") only falls back to the default when name is missing entirely, not when it's present but empty. A unit test could have caught it. I just hadn't thought to write one for that case. Good reminder that passing tests only prove what you actually tested for.
Understanding @pytest.fixture() took time. The decorator pattern — where a function is registered by name and its return value is injected into tests automatically — is not intuitive if you are used to calling functions directly. The key insight: by the time the fixture value arrives in your test, it is no longer a function. It is just a value — whatever the fixture returned.
The python -m pip install vs pip install distinction caused a real failure. The error was ModuleNotFoundError: No module named 'requests' even after installing it. The Windows Store Python creates a separate environment that pip alone does not always target. Using python -m pip fixes it.
The Content-Type header difference between sam local and the real API Gateway surprised me. Local returns application/json. Deployed returns application/json; charset=utf-8. Using in instead of == in the assertion handles both environments without duplicating tests.

What I Learned

Unit tests prove your logic. Integration tests prove your wiring. A unit test that passes and an integration test that fails means your code is correct but your infrastructure is broken. Both layers are necessary.
403 Missing Authentication Token usually means a missing route, not a permissions problem. API Gateway returns this for any path not configured in template.yaml. Your Lambda's 404 only appears if Lambda actually runs — for unknown paths, it never does.
Passing tests only prove what you thought to test. 28 green tests felt like proof the API was solid. The empty-string bug was sitting there the whole time, untouched by any of those 28 checks.
Different test layers give you different chances to catch the same bug. The empty-string edge case could have been caught by a unit test, but it was not. It took a real HTTP request with a realistic, slightly unusual input to surface it. Testing the deployed API is not just about checking infrastructure — it is another opportunity to probe behaviour with inputs a real user might actually send.
Never trust automation before you have verified manually. Running curl against your deployed URL before writing integration tests is not optional. It is how you confirm the deployment worked before asking a test suite to confirm it for you.

Conclusion

You've now tested this API three different ways: unit tests against the raw Lambda handler, integration tests against the local API Gateway emulator, and integration tests against the real, deployed stack — 28 passing tests total, proving the API actually works, not just that it runs.

More importantly, you now know why each layer exists. The 403 vs 404 discovery showed that API Gateway rejects unknown paths before Lambda ever runs. Your unit tests could never catch that because they call Lambda directly and bypass API Gateway entirely. Only a real integration test — one that sends an actual HTTP request through the full stack — could expose it.

Then there's the empty-string bug: /hello?name= returned "Hello, !" instead of "Hello, World!", even with seven deployed tests all green. Nothing infrastructural was wrong. I just hadn't thought to test that specific case. It's now a permanent regression test, and a reminder that "all green" is a checkpoint, not a finish line

The biggest takeaway isn't the tests themselves. Passing the planned tests does not necessarily mean the application is ready. Continuing to test with different and unexpected inputs can reveal behavior that the original test cases did not cover.

Call to Action — Your Turn

You have 28 passing tests. Now break something on purpose and fix it.

Add a new endpoint to the API:

Add a GET /goodbye endpoint to app.py that returns {"message": "Goodbye, {name}!"}
Add the route to template.yaml under Events
Test it manually with sam local start-api and curl
Add a unit test for it in test_app.py
Add an integration test for it in test_api_gateway_local.py
Deploy with sam deploy
Test the deployed endpoint with curl
Add a deployed integration test for it in test_api_gateway_deployed.py
Run all 3 test layers and confirm everything passes

If you try it, drop a comment with your result — I would love to see what you build.

Connect with me on:

Build Your First AWS REST API the Smart Way — Unit & Integration Tests, Live Docs, and Infrastructure as Code

Gloria — Tue, 07 Jul 2026 11:00:00 +0000

Introduction

APIs are the foundation of modern software development, which is why this "Hello World!" API is anything but basic.

Most tutorials rush past the foundational concepts, pushing you to build complex systems before you truly understand how everything connects. This guide is different.
By the end, you won't just have a working API—you will understand exactly what is happening under the hood. More importantly, you will have a production-ready infrastructure that you can share, repeat, and version-control. This is the exact API that started my cloud journey. Building it gave me the foundational knowledge to later build a production serverless API that automates data tracking for 165 schools and saves me 25+ hours a year.
Looking back at that project, my biggest takeaway was realizing why we test production APIs using automated code rather than just console testing. This tutorial is me putting that vital lesson into practice.
By building this Hello World API, you will master the core fundamentals that power real-world production systems:

✅ HTTP request handling
✅ Query parameter extraction
✅ JSON response formatting
✅ CORS configuration
✅ Serverless deployment
✅ Infrastructure as Code
✅ Unit testing
✅ Integration testing
✅ Deployment to AWS

The pattern you will learn here — receive request → process data → return response — is the exact same blueprint used in every enterprise API, from simple microservices to complex distributed systems.

Every complex system starts right here. Master this fundamental pattern, and you can build anything.

The Smarter Way to Build Your First API

The AWS Management Console is a great place to start building and exploring APIs. Clicking through Lambda, API Gateway, and IAM helps you see exactly what AWS is creating under the hood. But here’s the thing: once you understand what each service does, manually clicking through the console becomes a major bottleneck:

Time-consuming: Taking 30+ minutes just to wire up a simple endpoint.
Error-prone: Forgetting critical settings when recreating the setup.
Unshareable: Preventing teammates from reliably reproducing your exact environment.
Untracked: Lacking version control, deployment history, or easy rollback.

That’s exactly why we’re using AWS SAM.

What is AWS SAM (Serverless Application Model)?

AWS SAM lets you define your entire API infrastructure in a single YAML file and deploy it with one command. No clicking through menus. No guesswork. Just clean, declarative Infrastructure as Code.

SAM lets you describe that same infrastructure: Lambda, API Gateway, IAM permissions in a single YAML file. One command builds it. One command deploys it. Anyone on your team can clone your repo and have the exact same API running in minutes.

Using the AWS Console is like picking your pizza toppings by hand—great for learning, but slow and easy to mess up. AWS SAM is your digital recipe card. You write the recipe once, hand it to AWS, and it bakes the exact same, perfect pizza with one click.
If a teammate wants that same pizza, you just hand them the recipe.

What Is a REST API?

A REST API (Representational State Transfer) is a way for applications to talk to each other over the internet using standard HTTP methods: GET, POST, PUT, DELETE.

Think of it like a waiter in a restaurant:

You (the client) place an order (HTTP request).
The waiter (the API) takes it to the kitchen (your server/Lambda).
The kitchen prepares it and the waiter brings back your food (JSON response).

Every time you use a weather app, log into a website, or pay online, a REST API is working behind the scenes.

Why REST Over Other API Styles?

There are several ways to design an API but REST remains the industry standard for a wide range of web and mobile applications. Here is how it compares to other common styles:

REST (Best for Web & mobile apps): Simple, stateless, works everywhere, maximum configuration control.
HTTP API (Best for High-speed, low-cost use cases): Fewer features but faster performance, less control.
GraphQL (Best for Complex, flexible data queries): Overkill for beginners.
WebSocket (Best for Real-time chat, live feeds): Wrong tool for request/response pattern.

AWS offers both REST API and HTTP API in API Gateway. HTTP API is cheaper and faster, but REST API gives you more control like request validation, usage plans, API keys, and detailed metrics. For learning, REST API teaches you more.

Why REST Is the Industry Standard:

Human-readable: URLs like /hello?name=Gloria make sense instantly
Stateless: every request carries everything the server needs, no sessions
Works everywhere: browsers, mobile apps, CLI tools, other servers
Scales effortlessly: especially paired with serverless like AWS Lambda

In this tutorial, we will build and deploy a REST API to AWS using AWS SAM, complete with unit tests, integration test, a live documentation endpoint and finally deploying to production AWS.

Let’s build it.

What We’re Building

A REST API with three endpoints:

GET / : Serves a live documentation page
GET /hello : Returns a personalised JSON greeting
GET /get-documentation : Also serves the documentation page

Prerequisites

Before starting, ensure you have these tools installed and configured:

AWS account — New AWS customers can get started at no cost with the AWS Free Tier
AWS CLI — AWS Command Line Interface (configured with your credentials)
Docker Desktop — User-friendly platform for container management
Git Bash — Provides a Unix-like terminal for Windows users
VS Code — Open source AI code editor (or any code editor)
SAM CLI — installed and ready
Git Bash / curl — Command line testing
Pytest

Quick Verification

Run these commands to confirm everything is set up correctly:

# Check AWS CLI  
aws --version  

# Verify AWS credentials are configured  
aws sts get-caller-identity  

# Check SAM is installed  
sam --version  

# Check Python is installed  
python --version  

# Check Docker  
docker --version

Step 1: Create the Project Structure

Open Git Bash or the Windows command prompt and initialize your project directory by running the following commands:

# Check and note your working directory before creating folders  
pwd  

# Create project folders  
mkdir hello-world-api  

# Create template.yaml file  
touch template.yaml  

# Navigate to hello-world-api and create another folder  
cd hello-world-api  
mkdir hello_world  

# Create app.py file inside hello_world  
touch app.py

Use Windows Explorer to navigate to the hello-world-api folder, right-click on the folder, and select Open with Code. Your folder structure should look like this in VS Code:

hello-world-api/  
├── hello_world/  
│   └── app.py        ← Lambda function goes here  
└── template.yaml     ← SAM infrastructure goes here

Step 2: Create the Lambda Function

Open app.py and paste in the following code:

import json
import datetime


COMMON_HEADERS = {
    "Access-Control-Allow-Origin": "*"
}


def lambda_handler(event, context):

    method = event.get("httpMethod", "")
    path = event.get("path", "/")

    # Only GET endpoints supported
    if method != "GET":
        return error_response(405, "Method not allowed")

    # Routing
    if path == "/":
        return documentation_handler()

    if path == "/get-documentation":
        return documentation_handler()

    if path == "/hello":
        return hello_handler(event)

    return error_response(404, "Endpoint not found")


def hello_handler(event):
    query_params = event.get("queryStringParameters") or {}
    name = query_params.get("name", "World")

    response_body = {
        "message": f"Hello, {name}!",
        "timestamp": datetime.datetime.now(datetime.UTC).isoformat(),
        "method": event.get("httpMethod", "UNKNOWN"),
        "path": event.get("path", "UNKNOWN"),
        "version": "1.0"
    }

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


def documentation_handler():
    html_content = """
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Hello API Docs</title>
        <link rel="icon" href="data:,">
        <style>
            * { margin: 0; padding: 0; box-sizing: border-box; }
            body {
                font-family: 'Segoe UI', sans-serif;
                background: #0f1117;
                color: #ffffff;
                min-height: 100vh;
                padding: 48px 24px;
            }
            .container { max-width: 720px; margin: 0 auto; }
            .badge {
                display: inline-block;
                background: #ff9900;
                color: #000;
                font-size: 11px;
                font-weight: 700;
                letter-spacing: 1px;
                padding: 4px 12px;
                border-radius: 20px;
                margin-bottom: 24px;
                text-transform: uppercase;
            }
            h1 { font-size: 28px; font-weight: 700; margin-bottom: 8px; }
            .subtitle { color: #8b8fa8; font-size: 15px; margin-bottom: 40px; }
            .card {
                background: #1a1d27;
                border: 1px solid #2a2d3e;
                border-radius: 12px;
                padding: 24px;
                margin-bottom: 16px;
            }
            .endpoint-row {
                display: flex;
                align-items: center;
                gap: 12px;
                margin-bottom: 12px;
            }
            .method {
                background: #1a4731;
                color: #4ade80;
                font-size: 12px;
                font-weight: 700;
                padding: 4px 10px;
                border-radius: 6px;
                font-family: monospace;
            }
            .path {
                font-family: monospace;
                font-size: 15px;
                color: #ff9900;
            }
            .description { color: #8b8fa8; font-size: 14px; margin-bottom: 16px; }
            .param-label {
                font-size: 11px;
                text-transform: uppercase;
                letter-spacing: 1px;
                color: #555870;
                margin-bottom: 8px;
            }
            .param-row {
                display: flex;
                gap: 12px;
                font-size: 13px;
                padding: 8px 0;
                border-bottom: 1px solid #2a2d3e;
                align-items: baseline;
            }
            .param-row:last-child { border-bottom: none; }
            .param-name { font-family: monospace; color: #ff9900; min-width: 80px; }
            .param-type { color: #555870; min-width: 60px; }
            .param-desc { color: #8b8fa8; }
            .response-box {
                background: #0f1117;
                border: 1px solid #2a2d3e;
                border-radius: 8px;
                padding: 16px;
                font-family: monospace;
                font-size: 13px;
                color: #4ade80;
                margin-top: 16px;
                white-space: pre;
            }
        </style>
    </head>
    <body>
        <div class="container">
            <div class="badge">API Documentation</div>
            <h1>Hello API</h1>
            <p class="subtitle">A beginner-friendly serverless REST API built with AWS SAM &amp; Lambda &middot; v1.0</p>

            <div class="card">
                <div class="endpoint-row">
                    <span class="method">GET</span>
                    <span class="path">/hello</span>
                </div>
                <p class="description">
                    Returns a personalised hello message. Pass a name as a query parameter or default to "World".
                </p>

                <div class="param-label">Query parameters</div>
                <div class="param-row">
                    <span class="param-name">name</span>
                    <span class="param-type">string</span>
                    <span class="param-desc">Optional. The name to greet. Defaults to "World".</span>
                </div>
            </div>

            <div class="card">
                <div class="endpoint-row">
                    <span class="method">GET</span>
                    <span class="path">/get-documentation</span>
                </div>
                <p class="description">
                    Returns this documentation page as an HTML response. Demonstrating that Lambda can serve HTML, not just JSON.
                </p>

                <div class="param-label">No parameters</div>
                <div class="param-row">
                    <span class="param-name">-</span>
                    <span class="param-type"></span>
                    <span class="param-desc">No query parameters required.</span>
                </div>
            </div>
        </div>
    </body>
    </html>
    """

    return {
        "statusCode": 200,
        "headers": {
            **COMMON_HEADERS,
            "Content-Type": "text/html"
        },
        "body": html_content
    }


def error_response(status_code, error_message):
    return {
        "statusCode": status_code,
        "headers": {
            **COMMON_HEADERS,
            "Content-Type": "application/json"
        },
        "body": json.dumps({
            "error": error_message
        })
    }

2.1 Understanding the Lambda Function Code

app.py contains four functions. Here's what each one does:

2.1.1 def lambda_handler(event, context): the entry point

Every Lambda function must have this exact signature. AWS calls this function and passes two things:

event — information about what triggered the Lambda; in our case, the HTTP request
context — metadata about the function execution (request ID, time remaining, etc.)

method = event.get("httpMethod", "")  
path = event.get("path", "/")

These two lines extract the HTTP method and path from the incoming request and store them in variables.

Note: event only exists when a request comes in. It is created fresh for every single invocation.

The routing block then directs each request to the right handler:

# Only GET endpoints supported  
    if method != "GET":  
        return error_response(405, "Method not allowed")  

    # Routing  
    if path == "/":  
        return documentation_handler()  

    if path == "/get-documentation":  
        return documentation_handler()  

    if path == "/hello":  
        return hello_handler(event)  

    return error_response(404, "Endpoint not found")

Good to know: The error_response(405, ...) for non-GET methods is not just good practice. It also saves Lambda cost by rejecting invalid requests immediately at the API Gateway before they reach Lambda.

2.1.2 def hello_handler(event): the main API logic

The hello_handler function serves as the central API logic. It processes GET /hello requests by first extracting the name query parameter from each request, builds the JSON response body and return data(hello greeting) to the client. This is where we implement the fundamental pattern of every API:

Extract parameters from the event (request):

query_params = event.get("queryStringParameters") or {}  
name = query_params.get("name", "World")

First, it extracts the query parameters from the event. For example, if you type http://localhost:3000/hello?name=John in your browser:

query_params would be: {"name": "John"}
The {} is a default : it tells Lambda that if there are no query parameters, use an empty dictionary instead of crashing.

The or {} is important because API Gateway can pass None for queryStringParameters when there are no query params, and calling .get() on None would crash.

Build the response body: The response must follow this exact format for API Gateway:

response_body = {
        "message": f"Hello, {name}!",
        "timestamp": datetime.datetime.now(datetime.UTC).isoformat(),
        "method": event.get("httpMethod", "UNKNOWN"),
        "path": event.get("path", "UNKNOWN"),
        "version": "1.0"
    }

Return data:

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

Lambda must return this exact format for API Gateway:

statusCode: 200 : HTTP success code (200 = OK)
headers : HTTP headers to send back, including:
Content-Type: application/json : tells the browser "this is JSON"
Access-Control-Allow-Origin: * : allows any website to call this API (CORS)
body : the actual response (must be a STRING, so we convert the dictionary to JSON with json.dumps())

Note: It is important to use json.dumps() otherwise Lambda will return a raw dictionary as the body, which Lambda will accept, but API Gateway won't know what to do with it and will fail to properly format the response for the client.

2.1.3 def documentation_handler() — the HTML endpoint

This is the part that surprises most beginners: Lambda can return HTML, not just JSON. The only thing that changes is one header:

"Content-Type": "text/html"    # ← this tells the browser to render a page

Compare above content-Type to /hello:

"Content-Type": "application/json"   # ← this tells the browser to display raw JSON

Same Lambda, same API Gateway but completely different browser behavior, controlled by a single header.

2.1.4 def error_response(status_code, message) — consistent error handling

Every error response goes through this function, which ensures CORS headers are always included. This matters because if a browser receives a 404 without a CORS header, it blocks the response entirely and the client gets a confusing network error instead of the actual error message.

To this point you have learned the four fundamentals of every API:

receive a request,

extract parameters

build a response, and

return data

Master this pattern and you master every API you'll ever build. Well done for coming this far!

Step 3: Define Your Infrastructure in `template.yaml`

Open template.yaml and paste in the following:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Description: Hello API - A beginner-friendly serverless REST API built with AWS SAM and Lambda

Globals:
  Function:
    Timeout: 10
    Runtime: python3.11
    MemorySize: 128

Resources:

  # API Gateway
  HelloWorldApi:
    Type: AWS::Serverless::Api
    Properties:
      Name: HelloWorldApi
      StageName: Prod
      TracingEnabled: true

      MethodSettings:
        - ResourcePath: '/*'
          HttpMethod: '*'
          ThrottlingBurstLimit: 100
          ThrottlingRateLimit: 50
          MetricsEnabled: true

      Cors:
        AllowMethods: "'GET,OPTIONS'"
        AllowOrigin: "'*'"
        AllowHeaders: "'Content-Type'"

  # Lambda Function
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: HelloWorldFunction
      CodeUri: hello_world/
      Handler: app.lambda_handler
      Description: Beginner-friendly serverless Hello API

      Events:

        RootApi:
          Type: Api
          Properties:
            RestApiId: !Ref HelloWorldApi
            Path: /
            Method: get

        HelloApi:
          Type: Api
          Properties:
            RestApiId: !Ref HelloWorldApi
            Path: /hello
            Method: get

        DocumentationApi:
          Type: Api
          Properties:
            RestApiId: !Ref HelloWorldApi
            Path: /get-documentation
            Method: get


Outputs:

  RootUrl:
    Description: Root URL - serves documentation page
    Value: !Sub "https://${HelloWorldApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/"

  HelloApiUrl:
    Description: Hello endpoint
    Value: !Sub "https://${HelloWorldApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello"

  DocumentationUrl:
    Description: Documentation endpoint
    Value: !Sub "https://${HelloWorldApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/get-documentation"

  HelloWorldFunctionArn:
    Description: Lambda function ARN
    Value: !GetAtt HelloWorldFunction.Arn

  HelloWorldFunctionIamRole:
    Description: IAM role ARN created for the Lambda function
    Value: !GetAtt HelloWorldFunctionRole.Arn

Understanding the SAM Template

The template is organized into four sections.

Version declaration and Transform

AWSTemplateFormatVersion: '2010-09-09'

This tells AWS “I’m using CloudFormation syntax from 2010–09–09.”

Transform: AWS::Serverless-2016-10-31

This line converts the SAM syntax into full CloudFormation. SAM is like a shortcut language that gets translated into longer CloudFormation code. Without this, AWS wouldn’t understand SAM-specific resources.

Globals

Globals:  
  Function:  
    Timeout: 10  
    Runtime: python3.11  
    MemorySize: 128

These are default settings applied to every Lambda function in the template. Setting them once here means you don’t have to repeat them for every function.

Timeout: 10 : kills the function if it runs longer than 10 seconds, preventing runaway costs
Runtime: python3.11: the Python version used to run the code
MemorySize: 128: the minimum RAM allocation, keeping costs low for a simple API

Resources

This section contains everything that AWS creates. The template groups resources into two parts:

1. API Gateway

The template defines the API Gateway resource explicitly so we can attach settings like throttling and CORS:

Resources:

  # API Gateway
  HelloWorldApi:
    Type: AWS::Serverless::Api
    Properties:
      Name: HelloWorldApi
      StageName: Prod
      TracingEnabled: true

      MethodSettings:
        - ResourcePath: '/*'
          HttpMethod: '*'
          ThrottlingBurstLimit: 100
          ThrottlingRateLimit: 50
          MetricsEnabled: true

      Cors:
        AllowMethods: "'GET,OPTIONS'"
        AllowOrigin: "'*'"
        AllowHeaders: "'Content-Type'"

StageName: Prod: creates /Prod in your URL: https://abc123.execute-api.us-east-1.amazonaws.com/Prod/hello. You can have multiple stages later: Dev, Test, Prod.
TracingEnabled: true : enables AWS X-Ray for distributed tracing, useful for debugging performance issues.
ThrottlingBurstLimit: 100 / ThrottlingRateLimit: 50: limits how many requests the API can handle per second, protecting both your Lambda function and your AWS bill.
MetricsEnabled: true: sends API metrics (request count, errors, latency) to CloudWatch.
Cors: allows browsers to call this API from any website. AllowOrigin: "*" is fine for learning; in production you would restrict this to specific domains.

Lambda Function

# Lambda Function
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: HelloWorldFunction
      CodeUri: hello_world/
      Handler: app.lambda_handler
      Description: Beginner-friendly serverless Hello API

FunctionName: HelloWorldFunction: the name AWS gives this Lambda function.
CodeUri: hello_world/ : tells SAM where your Lambda code lives.
Handler: app.lambda_handler : the format is filename.function_name, so this means "call the lambda_handler function inside app.py", i.e. def lambda_handler(event, context).
Description : a short description of what the function does.

Events

The Events block describes which API routes trigger the Lambda function. Three events are defined in this template:

Events:

        RootApi:
          Type: Api
          Properties:
            RestApiId: !Ref HelloWorldApi
            Path: /
            Method: get

        HelloApi:
          Type: Api
          Properties:
            RestApiId: !Ref HelloWorldApi
            Path: /hello
            Method: get

        DocumentationApi:
          Type: Api
          Properties:
            RestApiId: !Ref HelloWorldApi
            Path: /get-documentation
            Method: get

**RootApi** : handles GET / request
**HelloApi**: handles GET /hello request
**DocumentationApi**: handles GET /get-documentation request

For each event:

RestApiId: !Ref HelloWorldApi : attaches the route to the API Gateway defined above. Without this, SAM would automatically create a second, separate API Gateway.
Path: defines the API endpoint URL (e.g. /hello).
Method: get: only GET requests are allowed on these routes.

Full Resources block:

Resources:

  # API Gateway
  HelloWorldApi:
    Type: AWS::Serverless::Api
    Properties:
      Name: HelloWorldApi
      StageName: Prod
      TracingEnabled: true

      MethodSettings:
        - ResourcePath: '/*'
          HttpMethod: '*'
          ThrottlingBurstLimit: 100
          ThrottlingRateLimit: 50
          MetricsEnabled: true

      Cors:
        AllowMethods: "'GET,OPTIONS'"
        AllowOrigin: "'*'"
        AllowHeaders: "'Content-Type'"

  # Lambda Function
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: HelloWorldFunction
      CodeUri: hello_world/
      Handler: app.lambda_handler
      Description: Beginner-friendly serverless Hello API

      Events:

        RootApi:
          Type: Api
          Properties:
            RestApiId: !Ref HelloWorldApi
            Path: /
            Method: get

        HelloApi:
          Type: Api
          Properties:
            RestApiId: !Ref HelloWorldApi
            Path: /hello
            Method: get

        DocumentationApi:
          Type: Api
          Properties:
            RestApiId: !Ref HelloWorldApi
            Path: /get-documentation
            Method: get

Outputs

These are values displayed on the screen after deployment. They give you the live URLs and resource identifiers for your deployed stack.

Outputs:

  RootUrl:
    Description: Root URL - serves documentation page
    Value: !Sub "https://${HelloWorldApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/"

  HelloApiUrl:
    Description: Hello endpoint
    Value: !Sub "https://${HelloWorldApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello"

  DocumentationUrl:
    Description: Documentation endpoint
    Value: !Sub "https://${HelloWorldApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/get-documentation"

  HelloWorldFunctionArn:
    Description: Lambda function ARN
    Value: !GetAtt HelloWorldFunction.Arn

  HelloWorldFunctionIamRole:
    Description: IAM role ARN created for the Lambda function
    Value: !GetAtt HelloWorldFunctionRole.Arn

Understanding output

**RootUrl** : the root endpoint of your API (/). This is where the documentation page is served.
**HelloApiUrl** : the /hello endpoint URL.
**DocumentationUrl**: the /get-documentation endpoint URL.
**HelloWorldFunctionArn** : the Amazon Resource Name (ARN) of your Lambda function. Useful for referencing the function in other AWS services or IAM policies.
**HelloWorldFunctionIamRole**: the ARN of the IAM role automatically created for your Lambda function by SAM.

Understanding `!Sub`

!Sub is a CloudFormation intrinsic function that means "substitute variables". It replaces placeholders in the string with their actual values at deploy time:

${HelloWorldApi} — the API Gateway ID, auto-generated by AWS when the stack is created.
${AWS::Region} — the AWS region the stack is deployed to (e.g. us-east-1).

So a value like:

!Sub "https://${HelloWorldApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello"

becomes something like:

https://abc123.execute-api.us-east-1.amazonaws.com/Prod/hello

Understanding `!GetAtt`

!GetAtt retrieves an attribute of a resource created in the same template. For example:

!GetAtt HelloWorldFunction.Arn:gets the ARN of the HelloWorldFunction Lambda.
!GetAtt HelloWorldFunctionRole.Arn : gets the ARN of the IAM role SAM automatically created for your Lambda.

Summary of what the SAM Template Does

The SAM template performs 5 major functions:

**Globals** — sets default Lambda settings (timeout, runtime, memory).
**API Gateway** — creates and configures the API Gateway with throttling, CORS, and metrics.
**Function** — creates the Lambda function and wires up the code.
**Events** — connects API routes (/, /hello, /get-documentation) to the Lambda function.
**Outputs** — displays the live URLs and resource ARNs after deployment.

Step 4: A Note on Security

For a beginner-friendly REST API, there isn’t much security configuration needed. However, a few things in this template already protect you:

Method validation in **app.py** : the if method != "GET" check rejects all non-GET requests before any real work happens, protecting your Lambda function from unnecessary invocations and cost.
Throttling : ThrottlingBurstLimit and ThrottlingRateLimit protect against traffic spikes and accidental (or intentional) overuse.
IAM role : SAM automatically creates a least-privilege IAM role for your Lambda function. You don’t define it manually — SAM handles it, and the role ARN appears in your Outputs after deployment.

Step 5: Validate the Template

Before building, check that your template.yaml is valid:

sam validate

You should see: template.yaml is a valid SAM Template

Step 6: Build the Application

This packages your Lambda function and prepares everything for deployment or local testing. Run this every time you change app.py or template.yaml.

sam build

Step 7: Run the API Locally

Note: Docker Desktop must be running before you execute sam local start-api. SAM uses Docker to simulate the Lambda environment locally. If Docker is not started, you will see an error like Error: Running AWS SAM projects locally requires Docker and the local API will not start.

sam local start-api

This starts a local API server on the default port 3000. If port 3000 is already in use (for example, by a React or Node.js dev server), use a different port:

sam local start-api --port 8080

Note: The first time you run sam local start-api, don't panic when you see a stream of dots filling your terminal. That's completely normal! SAM is pulling the Python 3.11 Lambda runtime image from Docker Hub layer by layer. Depending on your internet speed, this can take a minute or two or more. Once it's done, you will see Mounting HelloWorldFunction at http://127.0.0.1:3000 and your API is ready. On future runs, use --skip-pull-image to skip this step.

Step 8: Test the Endpoints

8.1 Using the Browser

Test **GET /hello** endpoint without name parameter should default to world

Once your terminal shows Running on http://127.0.0.1:3000 follow these steps:

Keep the terminal running. Do not close it. Closing it stops your local API.
Open Chrome browser and enter http://localhost:3000/hello in the URL bar
Switch back to your terminal and you will should see a log line confirming the request was handled, with an HTTP 200 status code
Switch back to your browser to see your JSON response

Test **GET /hello** endpoint with name parameter should show greeting with your name.

Open chrome browser and type this:

http://localhost:3000/hello?name=YourName — the message updates with your name

Test GET /get-documentation — should serve the documentation page:

Enter this in a new tab in your browser:

http://localhost:3000/get-documentation — you should see the styled documentation page

Test the root / endpoint — should also serve the documentation page

Enter this in a new tab in your browser: http://localhost:3000/

8.2 Using curl (Git Bash or Command Prompt)

sam local start-api takes over the terminal it runs in. It stays running and logs every request in real time. To test with curl, you need a second terminal alongside it.

Windows users: If you are using PowerShell, curl is actually an alias for Invoke-WebRequest and gives a very different output — verbose headers, status codes, and a security warning. Use Git Bash for all the commands in this section instead. Alternatively, type curl.exe instead of curl in PowerShell to call the real curl binary directly and get the same clean output.

Here’s the flow:

Terminal 1 — start the API and leave it running:

sam local start-api

Terminal 2 — open a new Git Bash window and run this curl command to test the /hello endpoint:

curl http://localhost:3000/hello

Terminal 2 shows the actual JSON response from curl.

Switch back to Terminal 1. You will see the request logged with the HTTP status code:

Invoking app.lambda_handler (python3.11)                                                                                                    
Requested to skip pulling images ...                                                                                                        

Mounting C:\Users\globa\hello-world-api\.aws-sam\build\HelloWorldFunction as /var/task:ro,delegated, inside runtime container               
START RequestId: c607d6bd-84bd-4eab-8588-e971dc303056 Version: $LATEST
[DEBUG] Lambda invoked - method: GET, path: /hello
END RequestId: e4960c8a-e470-4b02-872c-852722317cbd
REPORT RequestId: e4960c8a-e470-4b02-872c-852722317cbd  Init Duration: 0.20 ms  Duration: 144.05 ms     Billed Duration: 145 ms Memory Size: 128 MB Max Memory Used: 128 MB

2026-06-29 14:56:08 127.0.0.1 - - [29/Jun/2026 14:56:08] "GET /hello HTTP/1.1" 200 -

Note: This two-terminal pattern is standard in API development. One terminal runs the server, the other sends requests.

Test /hello endpoint with a name parameter:

Type this in terminal 2:

curl http://localhost:3000/hello?name=Gloria

Test GET /get-documentation — should serve the documentation page:

curl http://localhost:3000/get-documentation

Test the root / endpoint should display the documentation page source:

curl http://localhost:3000/

8.3 Testing Non-GET Methods

Once your GET requests are working, it’s worth sending one or two non-GET requests to see exactly how API Gateway protects your Lambda function.

Open a second terminal (leave Terminal 1 running with sam local start-api) and run:

Note: Browsers can only send GET requests from the address bar. You cannot test POST or PUT methods directly in a browser. Use curl, Git Bash, or curl.exe (PowerShell) in a second terminal as shown below.

# Test POST — should be blocked  
curl -X POST http://localhost:3000/hello  

# Test PUT - should be blocked  
curl -X PUT http://localhost:3000/hello

Now switch back to Terminal 1 and compare the POST and PUT request logs(Figure 14) with GET request logs in Figure 15:

POST and PUT request logs

GET request log

Notice what's missing in POST and PUT request logs(Figure 14):
No START RequestId, no Billed Duration. The POST and PUT requests were rejected by API Gateway — they never reached your Lambda function. This is exactly what method validation is for. It protects both your function and your AWS bill.

Why does API Gateway return **{"message": "Missing Authentication Token"}** instead of your Lambda's 405 error?

When you send a POST or PUT request, API Gateway checks your template.yaml first. Since only GET is configured for these routes, API Gateway doesn't recognize the method and returns its own default error, before your Lambda function is ever invoked. Despite the confusing name, this message simply means "I don't know what to do with this request." Your Lambda's 405 error would only appear if Lambda was invoked directly, bypassing API Gateway entirely. This is actually good news: the block happens at the gateway level, so Lambda is never called and you are never billed.

Step 9: Automated Testing — Unit Tests

A unit test is a Python script that calls your Lambda function directly — without API Gateway, without SAM, without a running server and checks that the output is exactly what you expected.

Instead of manually opening a browser and typing localhost:3000/hello?name=Gloria every time you make a change, a unit test does that check automatically in one command.

A unit test checks one small piece of your code in complete isolation. No internet. No AWS. No real API Gateway. Just your Python functions.

Unit tests catch bugs before your code reaches AWS. Instead of sending a real HTTP request, you simulate the inputs (the event dictionary that API Gateway normally builds) and check the outputs. This is fast, free, and repeatable.

Why Automated Testing Catches More Than Console Testing

When you test on the console or browser, you only see what the surface shows. For example, API Gateway does not explicitly display "Endpoint not found" when you hit an unknown path — it just returns a generic error and you might think everything is fine.

Automated tests look beneath the surface. They check the actual values in the response — the status code, the error message, the headers: things the console never shows you. That's why you will notice we have far more tests here than things you could verify manually in a browser. A browser tells you "it worked" or "it didn't." A unit test tells you exactly what worked, what didn't, and why.

This is the real power of automated testing: it verifies the contract of your code, not just the appearance.

Step 10: Set Up the Test Structure

10.1 Create the `init.py` Files

These are empty files that tell Python “treat this folder as a package.” Without them, your imports will fail.

Run these commands from your project root:

On Git Bash:

# Create empty __init__.py files
touch hello_world/__init__.py
touch tests/__init__.py
touch tests/unit/__init__.py

On Windows (Command Prompt):

type nul > hello_world\__init__.py
type nul > tests\__init__.py
type nul > tests\unit\__init__.py

10.2 Create a `pytest.ini` File

Create a pytest.ini file in the root of your project:

# Create pytest.ini files  
touch hello-world-api/pytest.ini

Add this content:

[pytest]  
pythonpath = .

This single line adds the project root to Python’s search path. Without it, from hello_world.app import ... fails because Python can't find the hello_world folder.

10.3 Create the `tests/unit/test_app.py` File

# Create test_app.py files  
touch hello-world-api/tests/unit/test_app.py

Your project should now look like this:

hello-world-api/
├── hello_world/
│   ├── __init__.py       ← makes it a Python package (importable)
│   └── app.py
├── tests/
│   ├── __init__.py       ← makes tests a package
│   └── unit/
│       ├── __init__.py   ← makes unit a package
│       └── test_app.py   ← your test file
├── pytest.ini            ← tells pytest where to find your code
└── template.yaml

Open test_app.py and paste in the following code:

import json
import pytest

from hello_world.app import lambda_handler, hello_handler, documentation_handler, error_response

# In real life, AP1 Gateway builds the "event" dict and passes it to Lambda.
# In unit test, you build the dict yourself. This is called mocking

def mock_event(method="GET", path="/", query_params=None):
    """
    Build a minimal API Gateway event dictionary.

    Args:
        method (str): HTTP method, e.g. "GET" or "POST"
        path   (str): URL path, e.g. "/hello"
        query_params (dict): Optional query string params, e.g. {"name": "Gloria"}

    Returns:
        dict: A fake API Gateway event our Lambda can process
    """
    return {
        "httpMethod": method,
        "path": path,
        "queryStringParameters": query_params
    }

# SECTION 1: TEST ROUTING
# Test that Lambda_handler sends request to the right places

def test_get_hello_returns_200():
    """GET /hello should return a greeting: 'Hello-World! (status 200)."""
    event = mock_event(method="GET", path="/hello")
    response = lambda_handler(event, context=None)
    assert response["statusCode"] == 200

def test_get_documentation_returns_200():
    """Get /get_documentation should return the documenttion page (status 200)."""
    event = mock_event(method="GET", path="/get-documentation")
    response = lambda_handler(event, context=None)
    assert response["statusCode"] == 200

def test_get_root_returns_200():
    """Get / should return the documentation page (status 200)."""
    event = mock_event(method="GET", path="/")
    response = lambda_handler(event, context=None)
    assert response["statusCode"] == 200

def test_unknown_path_returns_404_error():
    """
    GET /nonexistent path should return 404 error - Endpoint Not Found."""
    event = mock_event(method="GET", path="/nonexistent")
    response = lambda_handler(event, context=None)
    assert response["statusCode"] == 404

def test_unknown_method_returns_405():
    """POST request should return 405 error - Method Not Allowed."""
    event = mock_event(method="POST", path="/hello")
    response = lambda_handler(event, context=None)
    assert response["statusCode"] == 405

def test_put_method_returns_405():
    """
    PUT requst should return 405 error - Method not Allowed"""
    event = mock_event(method="PUT", path="/hello")
    response = lambda_handler(event, context=None)
    assert response["statusCode"] == 405

# SECTION 2: TEST HELLO HANDLER
# Test the actual logic of /hello endpoint

def test_hello_handler_without_name_parameter():
    """/hello without name parameter should default to 'Hello-World!'"""
    event = mock_event(method="GET", path="/hello")
    response = hello_handler(event)
    body = json.loads(response["body"])
    assert body["message"] == "Hello, World!"

def test_hell0_handler_with_name_parameter():
    """/hello?name=Gloria should return 'Hello, Gloria!"""
    event = mock_event(method="GET", path="/hello", query_params={"name": "Gloria"})
    response = hello_handler(event)
    assert response["statusCode"] == 200
    body = json.loads(response["body"])
    assert body["message"] == "Hello, Gloria!"


def test_hello_handler_with_empty_queryparams_dict():
    event = mock_event(method="GET", path="/hello", query_params={})
    response = hello_handler(event)
    body = json.loads(response["body"])
    assert body["message"] == "Hello, World!"

def test_hello_handler_response_contains_timestamp():
    event = mock_event(method="GET", path="/hello")
    response = hello_handler(event)
    body = json.loads(response["body"])
    assert "timestamp" in body


# SECTION 3: TEST DOCUMENTATION HANDLER
# Test /get-documentation and / endpoints

def test_documentation_handler_returns_200():
    """Test /get-documentation returns status 200"""
    response = documentation_handler()
    assert response["statusCode"]== 200

def test_documentation_content_type_is_html():
    """/get-documentation content-Type is 'test/html"""
    response = documentation_handler()
    assert response["headers"]["Content-Type"]== "text/html"


# SECTION 4
# TEST ERROR
    """
    WHY TEST THE ERROR HELPER?
    error_response is used for both 404 and 405. If it breaks, 
    the entire error handling breaks.
    """
def test_404_error_response():
    """
    Test 404 error response has correct status code and error message
    """
    response = error_response(400, "Endpoint not found")
    body = json.loads(response["body"])
    assert response["statusCode"] == 400
    assert body["error"] =="Endpoint not found"    

def test_405_error_response():
    """
    Test 405 error response has correct status code and error message
    """
    response = error_response(405, "Method not allowed")
    body = json.loads(response["body"])
    assert response["statusCode"] == 405
    assert body["error"] == "Method not allowed"

def test_error_response_cors_header_present():
    """Error responses needs CORS header."""
    response = error_response(404, "Endpoint not found")
    assert response["headers"]["Access-Control-Allow-Origin"] == "*"

Code Explanation

mock_event(method="GET", path="/", query_params=None) is a helper function that builds a fake API Gateway event.

In production, API Gateway builds the event dictionary and passes it to Lambda. In tests, you build it yourself. This is called mocking. You only include the fields your app.py actually reads, keeping it minimal and focused.

Test Routing

These tests hit lambda_handler — the front door of your API. If routing breaks, everything breaks. They verify:

GET / returns 200
GET /hello returns 200
GET /get-documentation returns 200
Unknown paths return 404
Non-GET methods (POST, PUT) return 405

Test Hello Handler

Notice json.loads(). Lambda returns body as a JSON string, not a dict. You must parse it back before checking individual fields.

These tests verify:

Named greeting works (?name=Gloria → Hello, Gloria!)
Default fallback works (no name → Hello, World!)
Both None and {} query params are handled — API Gateway can send either
Response always includes a timestamp field

Test Documentation Endpoint

Two things worth noting here:

The documentation endpoint returns text/html — tested explicitly because the wrong Content-Type would cause browsers to display raw text instead of a rendered page
Even error responses need CORS headers. If a browser gets a 404 without a CORS header, the browser blocks it and the client sees a confusing network error instead of the actual 404 message

Test Error Response

Each function tests one specific aspect of error_response():

test_404_error_response: test 404 error status code and error message are both correct.
test_405_error_response: test 405 error status code and error message are both correct.
test_error_response_cors_header_present: CORS headers must be present even on errors. Without them, browsers block the error response entirely and the client sees a confusing network error instead of the actual 404 or 405 message.

Step 11: Run the Unit Tests

First, install pytest if you haven’t already done so from the prerequisite section:

pip install pytest

Run this from your project root:

pytest tests/unit/test_app.py -v

The -v flag means verbose. It prints each test name so you can see exactly what passed or failed.

You should see something like this:

test/unit/test_app.py::test_hello_handler_response_contains_timestamp PASSED                                                                                 [ 66%]
test/unit/test_app.py::test_documentation_handler_returns_200 PASSED                                                                                         [ 73%]
test/unit/test_app.py::test_documentation_content_type_is_html PASSED                                                                                        [ 80%]
test/unit/test_app.py::test_404_error_response PASSED                                                                                                        [ 86%]
test/unit/test_app.py::test_405_error_response PASSED                                                                                                        [ 93%]
test/unit/test_app.py::test_error_response_cors_header_present PASSED                                                                                        [100%]

======================================================================= 15 passed in 0.16s ========================================================================

15 tests. 0.16 seconds. No AWS account needed.
Every time you change app.py, run pytest before you deploy. If a test fails, you caught the bug locally, not in production.

The pattern is simple: write code → write tests → deploy with confidence.

After the unit tests come integration tests, which are covered in Part 2 of this article.

Challenges:

Writing unit tests was the hardest part of this article. It required learning from multiple sources, comparing approaches, and deliberately settling on best practices rather than just copying the first example found. The learning curve is real, but it's worth it.
The __init__.py files were confusing at first. It wasn't obvious why empty files were needed at all. Once the concept of "Python packages" clicked — that __init__.py is what tells Python "treat this folder as importable" — everything fell into place.
Routing in app.py went through several iterations. The final clean structure didn't appear on the first try. It took a few rewrites before the cost optimization principle emerged: reject non-GET requests first, before any real work happens, to avoid unnecessary Lambda invocations.
Mapping Lambda to events in template.yaml wasn't intuitive — understanding that RestApiId: !Ref HelloWorldApi is what connects a route to your API Gateway (not a new one SAM creates automatically) took time to fully grasp.
Understanding why CORS headers matter on error responses was a hard-won insight. It feels counterintuitive at first. Why would a 404 need CORS? The answer: without it, the browser blocks the error entirely, and the client sees a confusing network failure instead of the actual error message.

What I Learned

A SAM template is a contract — it describes the infrastructure your code needs, and SAM handles creating it. Understanding template.yaml makes everything else — deployment, local testing, debugging — much less mysterious.
mock_event() is the heart of unit testing a Lambda function — once you understand that API Gateway just builds a dictionary and passes it to your function, testing becomes simple: build the dictionary yourself and check the output.
Automated tests reveal what the console hides: Console testing tells you whether something looks right. Automated tests tell you whether it is right including error messages, status codes, and headers that never appear on screen.
Write tests while you build, not after — tests written after the fact feel like chores. Tests written alongside the code feel like guardrails — you immediately see the value.

Conclusion

You’ve built a serverless REST API from scratch — a SAM template, a Lambda function with proper routing and error handling, a documentation endpoint, and a full unit test suite with 15 tests.

More importantly, you’ve developed a habit: write code → write tests → deploy with confidence. That loop is what separates code that probably works from code you can trust.

In Part 2, we’ll move from unit tests to integration tests — testing the real API Gateway, the real Lambda, and the real AWS infrastructure to make sure everything works end-to-end and final deployment to production AWS.

Resources

Connect with me on:

DEV Community: Gloria

Automated Integration Tests for the Deployed Hello World API

TL;DR — What We Built in Part 1

Introduction — What Part 2 Covers

What Is Integration Testing?

The 2 Types of Integration Tests This Project Implements

Prerequisites

Part 1: Local Integration Tests

Step 1: Create the Integration Test Folder

Step 2: Write the Local Integration Tests

Understanding the Test Code

Step 3: Run the Local Integration Tests

What You Should See — and One Surprise

Discovery #1: Why 403 and Not 404?

Part 2: Deploy the API to AWS

Step 1: Build and Deploy

Part 3: Manually Test the Deployed API Endpoints

Test Using the Browser

Using curl

Part 4: Automated Integration Tests for the Deployed Hello World API

Step 1: Create the Deployed Integration Test File

Step 2: Write the Deployed Integration Tests

Understanding the Test Code

Step 3: Set the Environment Variable

Step 4: Run the Deployed Integration Tests

What You Should See

Why 21 Seconds?

Discovery #2 — Empty Query Parameter Bug

Why It Happened

The Fix — Adding a Regression Test

Running All Three Layers Together

Challenges

What I Learned

Conclusion

Call to Action — Your Turn

Build Your First AWS REST API the Smart Way — Unit & Integration Tests, Live Docs, and Infrastructure as Code

Introduction

The Smarter Way to Build Your First API

What is AWS SAM (Serverless Application Model)?

What Is a REST API?

What We’re Building

Prerequisites

Quick Verification

Step 1: Create the Project Structure

Step 2: Create the Lambda Function

2.1 Understanding the Lambda Function Code

Step 3: Define Your Infrastructure in template.yaml

Understanding the SAM Template

Full Resources block:

Understanding output

Understanding !Sub

Understanding !GetAtt

Summary of what the SAM Template Does

Step 4: A Note on Security

Step 5: Validate the Template

Step 6: Build the Application

Step 7: Run the API Locally

Step 8: Test the Endpoints

8.1 Using the Browser

8.2 Using curl (Git Bash or Command Prompt)

8.3 Testing Non-GET Methods

Step 9: Automated Testing — Unit Tests

Why Automated Testing Catches More Than Console Testing

Step 10: Set Up the Test Structure

10.1 Create the __init__.py Files

10.2 Create a pytest.ini File

10.3 Create the tests/unit/test_app.py File

Code Explanation

Test Routing

Test Hello Handler

Test Documentation Endpoint

Test Error Response

Step 11: Run the Unit Tests

Challenges:

What I Learned

Conclusion

Step 3: Define Your Infrastructure in `template.yaml`

Understanding `!Sub`

Understanding `!GetAtt`

10.1 Create the `init.py` Files

10.2 Create a `pytest.ini` File

10.3 Create the `tests/unit/test_app.py` File