sam local start-api

sam local start-api

Local API Testing with sam local start-api

sam local start-api reads the template's Api events and serves them from a local HTTP server that imitates API Gateway 24 : each request becomes an API Gateway proxy event, runs in a fresh container, and the function's statusCode, headers and body become the HTTP response. It is the quickest loop for testing routes, status codes and bad input:

Serving the API locally on port 31300 and calling itYAML

sam local start-api --port 31300 --env-vars env.json --docker-network l1-sam 2>/dev/null &
sleep 8
curl -s localhost:31300/books | jq -c '.[0:2]'
curl -s -w ' HTTP %{http_code}\n' localhost:31300/books/9
curl -s -w ' HTTP %{http_code}\n' localhost:31300/books/nine
kill $!

Output

[{"id":1,"title":"The Quiet Harbor","price":14.99},{"id":2,"title":"Patterns of the Deep
  Web","price":39.5}]
{"error":"book not found"} HTTP 404
{"error":"id must be an integer"} HTTP 400

Code changes are picked up after sam build, without a deploy. A container per request is slow (about half a second each here); --warm-containers EAGER keeps one per function. The emulation is not API Gateway itself: authorizers, throttling, request validation and custom domains behave differently or not at all, so a deploy stays the real test. sam sync --watch pushes code changes to a deployed stack for that second loop.

MENU