DEV Community: Bry

Getting Started with the Claude API: Messages, Streaming, and Tool Use

Bry — Tue, 21 Jul 2026 15:00:00 +0000

Key Points

Install anthropic, set ANTHROPIC_API_KEY, and you have a working LLM API in five lines of Python.
Three models cover 95% of use cases: Opus for complex reasoning, Sonnet for most production tasks, Haiku for cheap high-volume classification.
Always stream long-form responses — timeouts and bad UX come from blocking on a full response.
Tool use requires a two-turn round trip: Claude signals a function call, your code runs it, you return the result.
Prompt caching cuts input token costs by up to 90% for apps that send the same system prompt on every request.

Introduction

Most tutorials for LLM APIs stop at "send a message, print a response." That gets you a demo. It does not get you a production application. I've integrated the Claude API into customer-facing applications and internal automation pipelines, and the same three gaps appear every time a team goes from prototype to production: they don't stream, they don't handle tool use as a round trip, and they only think about cost after the first billing cycle. The Claude API has specific patterns for streaming, tool use, and cost control that are non-obvious from a basic example — and getting them wrong results in timeouts, doubled costs, or silent logic errors when Claude tries to call a function and your code ignores it.

This article covers the full picture: how the Messages API works, how to pick the right model, how to stream correctly, how to implement tool use as a complete round trip, and how to keep costs predictable at scale. All code is Python 3.11+. The companion code at ai-integration/claude-api-quickstart/src/main.py is a runnable ClaudeClient class that demonstrates all four patterns.

Setup

Install the SDK and dependencies:

pip install anthropic python-dotenv

Store your API key as an environment variable — never hardcode it:

# .env
ANTHROPIC_API_KEY=sk-ant-...

The Anthropic SDK reads ANTHROPIC_API_KEY automatically. Initialize the client once at module level:

import os
from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()
client = Anthropic()  # reads ANTHROPIC_API_KEY from env

Create the client once. A common mistake is instantiating Anthropic() inside a request handler. The client maintains an HTTP connection pool — recreating it on every call wastes ~50ms in connection setup and adds unnecessary overhead.

Messages API Basics

Every interaction with Claude goes through client.messages.create(). The API uses three message roles:

system — sets the context and rules for the entire conversation. Not a message in the history.
user — input from the human (or your application).
assistant — Claude's previous responses. Include these to continue a multi-turn conversation.

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a senior backend engineer. Be concise and direct.",
    messages=[
        {"role": "user", "content": "What is the difference between process and thread?"}
    ]
)

print(response.content[0].text)
print(f"Tokens used — input: {response.usage.input_tokens}, output: {response.usage.output_tokens}")

Key parameters:

Parameter	Type	Notes
`model`	string	Required. See model selection section below.
`max_tokens`	int	Required. Upper bound on output — Claude stops here even mid-sentence.
`system`	string	Optional. Sets assistant persona and rules.
`messages`	list	Required. Alternating user/assistant turns. Must start with `user`.
`temperature`	float	0.0–1.0. Default 1.0. Lower = more deterministic. Use 0.0 for classification.
`stop_sequences`	list	Claude stops generating at any of these strings.

The response stop_reason tells you why Claude stopped:

end_turn — Claude finished naturally.
max_tokens — hit the max_tokens limit. Response may be truncated.
tool_use — Claude wants to call a function. Must handle this explicitly.
stop_sequence — hit one of your stop sequences.

Always check stop_reason. If you receive tool_use and ignore it, Claude is waiting for your function result — it did not finish answering your question.

Model Selection

Three production models cover nearly all use cases. Choose by task complexity and cost tolerance:

Model	ID	Best For	Not For
Claude Opus 4	`claude-opus-4-8`	Complex multi-step reasoning, code generation from ambiguous specs, research synthesis	High-volume tasks (cost), simple classification
Claude Sonnet 4	`claude-sonnet-4-6`	Most production API tasks, customer-facing chat, structured extraction	Tasks where you need the cheapest option
Claude Haiku 4	`claude-haiku-4-5-20251001`	Classification, summarization, high-volume extraction, quick one-turn answers	Multi-step reasoning, long-form generation

Default to claude-sonnet-4-6 for any new feature. I start every integration on Sonnet and only swap to Haiku after running a sample of real production inputs through both models and comparing outputs — not benchmarks, actual outputs for your specific task. Migrate to Haiku only after confirming the output quality is acceptable for that specific task.

Streaming Responses

For responses longer than a paragraph, stream. A non-streaming call for a 2,000-token response waits 10–30 seconds before returning anything to the user. Streaming begins returning tokens in ~200ms.

def stream_response(system: str, prompt: str) -> None:
    with client.messages.stream(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system=system,
        messages=[{"role": "user", "content": prompt}],
    ) as stream:
        for text in stream.text_stream:
            print(text, end="", flush=True)
    print()  # newline after stream ends

The with client.messages.stream() context manager handles connection cleanup. Inside the block, stream.text_stream yields each text delta as Claude generates it.

When to stream:

Any user-facing response longer than ~100 tokens.
Document generation, code generation, long explanations.

When not to stream:

Classification tasks where you need the complete label before doing anything.
Tool use — stream the full round trip only if you handle partial tool input JSON.
Batch processing jobs where individual response latency does not matter.

In practice, I default to streaming for anything user-facing and non-streaming for anything running in a background job. The distinction matters because mixing the two in the same codebase without clear conventions leads to subtle bugs when someone reuses a non-streaming helper in a latency-sensitive context.

Tool Use (Function Calling)

Tool use is a two-turn exchange. In turn one, Claude signals which function to call and with what arguments. Your application executes the function. In turn two, you send the result back, and Claude incorporates it into its final answer.

Define a tool

CALCULATOR_TOOLS = [
    {
        "name": "calculator",
        "description": "Performs basic arithmetic. Use when the user asks for a calculation.",
        "input_schema": {
            "type": "object",
            "properties": {
                "operation": {
                    "type": "string",
                    "enum": ["add", "subtract", "multiply", "divide"],
                    "description": "The arithmetic operation to perform."
                },
                "a": {"type": "number", "description": "First operand."},
                "b": {"type": "number", "description": "Second operand."}
            },
            "required": ["operation", "a", "b"]
        }
    }
]

Handle the round trip

import json

def use_tool(prompt: str) -> str:
    messages = [{"role": "user", "content": prompt}]

    # Turn 1: Claude may request a tool call
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=CALCULATOR_TOOLS,
        messages=messages,
    )

    if response.stop_reason != "tool_use":
        # Claude answered directly — no tool call needed
        return response.content[0].text

    # Extract the tool use block
    tool_use_block = next(b for b in response.content if b.type == "tool_use")
    tool_name = tool_use_block.name
    tool_input = tool_use_block.input

    # Execute the function locally
    result = _run_calculator(tool_input)

    # Turn 2: Return the tool result and get the final answer
    messages.append({"role": "assistant", "content": response.content})
    messages.append({
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": tool_use_block.id,
                "content": str(result),
            }
        ],
    })

    final = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=CALCULATOR_TOOLS,
        messages=messages,
    )
    return final.content[0].text


def _run_calculator(args: dict) -> float:
    a, b, op = args["a"], args["b"], args["operation"]
    if op == "add":       return a + b
    if op == "subtract":  return a - b
    if op == "multiply":  return a * b
    if op == "divide":
        if b == 0:
            raise ValueError("Division by zero")
        return a / b
    raise ValueError(f"Unknown operation: {op}")

The key detail: messages.append({"role": "assistant", "content": response.content}) — you must include Claude's entire response object (including the tool use block) in the history before sending the tool result. Sending only the text content breaks the conversation. I've seen this cause a 400 BadRequestError in production because a developer extracted just the text from the assistant response and discarded the tool use block before appending — the API rejects the resulting message history as structurally invalid, and the error message doesn't point to the exact field.

Error Handling and Retries

Rate limit errors and transient server errors are inevitable at any meaningful scale. I've seen a well-tested integration start hitting RateLimitError the week after launch simply because a new feature tripled the request volume — the app had no retry logic, and every error surfaced directly to the user as a 500. Implement exponential backoff from day one:

import time
import anthropic

def _create_with_retry(
    messages: list,
    model: str,
    max_tokens: int,
    system: str = "",
    max_retries: int = 3,
) -> anthropic.types.Message:
    for attempt in range(max_retries):
        try:
            kwargs = {
                "model": model,
                "max_tokens": max_tokens,
                "messages": messages,
            }
            if system:
                kwargs["system"] = system
            return client.messages.create(**kwargs)
        except anthropic.RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
        except anthropic.APIStatusError as e:
            if e.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise

Common exceptions:

Exception	Cause	Action
`anthropic.RateLimitError`	Too many requests	Exponential backoff
`anthropic.APIStatusError` (5xx)	Server error	Retry with backoff
`anthropic.BadRequestError`	Invalid request (context too long, invalid params)	Do not retry — fix the request
`anthropic.AuthenticationError`	Bad API key	Do not retry — check env var

Check token count before sending a long conversation to avoid BadRequestError on context overflow:

token_count = client.messages.count_tokens(
    model="claude-sonnet-4-6",
    messages=messages,
)
print(f"Prompt uses {token_count.input_tokens} tokens")

Cost Management and Prompt Caching

Claude charges per token: input tokens (what you send) and output tokens (what Claude generates). Output tokens cost 3–5× more per token than input tokens. The usage breakdown appears in every response:

print(response.usage.input_tokens)   # tokens you sent
print(response.usage.output_tokens)  # tokens Claude generated

Prompt caching

If your application sends the same system prompt on every request (a common pattern), prompt caching can reduce input costs by 60–90%. Mark the cacheable prefix with cache_control:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a senior backend engineer...\n[very long system prompt]",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": user_question}],
)

On the first call, Anthropic caches the marked prefix. Subsequent calls within the cache TTL pay ~10% of the normal input price for cached tokens. The response includes cache statistics:

print(response.usage.cache_creation_input_tokens)  # tokens written to cache
print(response.usage.cache_read_input_tokens)       # tokens read from cache (cheap)

When caching pays off: system prompts over ~1,000 tokens with more than a few calls per day. I enable caching by default on any app with a fixed system prompt longer than 500 tokens — the implementation cost is two lines and the savings compound quickly once you're past a few hundred daily active users. For shorter prompts or low-volume applications, the overhead is negligible.

Common Mistakes

Not streaming long-form responses. A blocking call for a 2,000-token response times out in some HTTP clients and always delivers a poor user experience. Use client.messages.stream() for any response that takes more than ~1 second.
Ignoring stop_reason. If stop_reason is tool_use and you return response.content[0].text, you are returning a partial or empty string — Claude was waiting to give you a real answer after executing the tool. I've seen this ship to production as a bug where the API "randomly" returned empty responses on certain questions — questions that happened to trigger tool use. Always check stop_reason before extracting text.
Setting max_tokens too low. If max_tokens is smaller than the full response, Claude stops mid-sentence and stop_reason returns max_tokens. The response is valid JSON but the content is truncated. Set max_tokens generously — you are not charged for unused headroom.
Recreating the Anthropic() client on every request. The client maintains an HTTP connection pool internally. Instantiating it per-request wastes connection setup time and bypasses the pool. Create one instance at module level and reuse it.
Sending unbounded conversation history. Every previous turn counts toward the input token cost. For long conversations, implement a windowing strategy: keep the system prompt, the last N turns, and trim the middle. Use client.messages.count_tokens() before every send to catch overruns early.

Full Example

The companion code at ai-integration/claude-api-quickstart/src/main.py implements all patterns above as a ClaudeClient class:

from dotenv import load_dotenv
from src.main import ClaudeClient

load_dotenv()
claude = ClaudeClient()

# Basic message
print(claude.send_message(
    system="You are a concise technical explainer.",
    prompt="What is a vector embedding in one sentence?",
))

# Streaming
for chunk in claude.stream_response(
    system="You are a Python expert.",
    prompt="Explain Python generators in detail.",
):
    print(chunk, end="", flush=True)

# Tool use
print(claude.use_tool("What is 2847 multiplied by 193?"))

Setup:

cd ai-integration/claude-api-quickstart
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env       # add your key
python -m src.main

Full source: GitHub link

State: The Conversation Turn Model

Conclusion

The difference between a Claude integration that works in a demo and one that holds up in production is not the model — it's whether you stream, whether you handle tool use as a complete round trip, and whether you have a cost strategy before your usage scales. Most production failures I've traced come back to one of those three. Ship an integration that gets all three right from the start, and you will spend your time building features instead of debugging silent errors and explaining surprise billing cycles to stakeholders.

Amazon API Gateway: REST vs HTTP APIs, Explained via the AWS CLI

Bry — Tue, 14 Jul 2026 15:00:00 +0000

Key Points

REST API and HTTP API are two separate products under one brand name, with two separate CLI command namespaces — aws apigateway and aws apigatewayv2. They are not versions of each other.
HTTP API costs $1.00 per million calls versus REST API's flat $3.50 per million — a 71% difference that compounds fast at scale.
Pick REST API only when you need something HTTP API structurally cannot do: API keys, per-client usage plans, AWS WAF, request validation, or private (VPC-only) endpoints.
The CLI reveals the real gap between them better than any feature table: building the same Lambda-backed endpoint takes one command on HTTP API and five on REST API.
Tear down what you build. Both products bill for idle resources, and orphaned stages are the most common line item nobody remembers creating.

Prerequisites

CLI/SDK version tested against: aws-cli/2.35.x (current stable as of this writing — the apigatewayv2 and apigateway command sets are stable across 2.x minor releases, but always run aws --version before following along)
An AWS account with an IAM user or role that has apigateway:* and lambda:* permissions, and a default region configured (aws configure)
A deployed Lambda function to integrate against — the examples below use a function named user-lookup

Introduction

Every AWS API Gateway tutorial I've read picks a product on page one and never explains why. Half of them build a REST API with create-resource and put-method chains that look like plumbing. The other half quick-create an HTTP API in one line and call it a day. Neither tells you when the other approach would have been the better call — and I've watched teams build a REST API out of habit, hit the $3.50-per-million bill at scale, and only then discover HTTP API existed.

The two products share a brand name and almost nothing else under the hood. They have separate CLI command namespaces, separate feature sets, and a 3.5x price difference that AWS designed on purpose, not as an afterthought. Understanding which one you're actually building — and why — matters more than memorizing either command sequence.

This article builds the identical Lambda-backed endpoint twice: once on HTTP API, once on REST API, entirely from the AWS CLI. You'll see where the commands diverge, where they can't diverge because one product simply lacks the feature, and which one to default to for your next project.

Two Products, Not Two Versions

AWS API Gateway is a brand covering three products: REST API, HTTP API, and WebSocket API. REST API launched in 2015. HTTP API launched in 2019 as a deliberately smaller product — AWS's own announcement framed it as coverage for the roughly 80% of REST API customers who only needed Lambda proxy integration, JWT auth, and CORS, and were paying REST API prices for features they never touched.

Diagram: One brand, two CLI namespaces, non-overlapping feature sets.

That last point trips people up the most: aws apigateway and aws apigatewayv2 are not "v1 and v2 of the same thing" the way S3's SDK versions are. They are two independent command trees. A script written for REST API will not run against HTTP API with a find-and-replace.

Building the Same Endpoint on HTTP API

Start with HTTP API, because it's shorter and shows what "quick create" actually collapses into one call.

# Quick-create an HTTP API backed directly by a Lambda function.
# This single command creates the API, a default catch-all route,
# a Lambda integration, and an auto-deploying default stage.
aws apigatewayv2 create-api \
  --name user-lookup-http \
  --protocol-type HTTP \
  --target "arn:aws:lambda:us-east-1:123456789012:function:user-lookup"

That one call is doing the work of five REST API calls, which is the point. Quick create only works for a single catch-all route. The moment you need more than one route with different backends, you build it up explicitly:

# Explicit build — needed once you have more than one route.
API_ID=$(aws apigatewayv2 create-api \
  --name user-lookup-http \
  --protocol-type HTTP \
  --query 'ApiId' --output text)

INTEGRATION_ID=$(aws apigatewayv2 create-integration \
  --api-id "$API_ID" \
  --integration-type AWS_PROXY \
  --integration-uri "arn:aws:lambda:us-east-1:123456789012:function:user-lookup" \
  --payload-format-version "2.0" \
  --query 'IntegrationId' --output text)

aws apigatewayv2 create-route \
  --api-id "$API_ID" \
  --route-key "GET /users/{userId}" \
  --target "integrations/$INTEGRATION_ID"

# HTTP API stages auto-deploy by default — no separate deployment call needed
aws apigatewayv2 create-stage \
  --api-id "$API_ID" \
  --stage-name '$default' \
  --auto-deploy

Four commands, no separate deployment step because $default auto-deploys on every change. Add a JWT authorizer — the feature HTTP API supports natively and REST API cannot without a Lambda authorizer standing in for it:

aws apigatewayv2 create-authorizer \
  --api-id "$API_ID" \
  --authorizer-type JWT \
  --identity-source '$request.header.Authorization' \
  --name user-pool-jwt \
  --jwt-configuration '{"Audience":["https://api.example.com"],"Issuer":"https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX"}'

Grant API Gateway permission to invoke the Lambda, and the endpoint is live:

aws lambda add-permission \
  --function-name user-lookup \
  --statement-id apigw-http-invoke \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:us-east-1:123456789012:${API_ID}/*/*/users/*"

curl "https://${API_ID}.execute-api.us-east-1.amazonaws.com/users/usr_42"

Total: five commands from zero to a JWT-protected, auto-deploying endpoint.

Building the Same Endpoint on REST API

Now the same endpoint on REST API. Structurally, REST API models resources as a tree — you create the API, then walk down from the root resource creating child resources, then attach an HTTP method and integration to each resource individually.

Diagram: REST API's resource-tree model requires an explicit deployment step that HTTP API's auto-deploy stages skip entirely.

API_ID=$(aws apigateway create-rest-api \
  --name user-lookup-rest \
  --endpoint-configuration types=REGIONAL \
  --query 'id' --output text)

ROOT_ID=$(aws apigateway get-resources \
  --rest-api-id "$API_ID" \
  --query 'items[?path==`/`].id' --output text)

USERS_ID=$(aws apigateway create-resource \
  --rest-api-id "$API_ID" \
  --parent-id "$ROOT_ID" \
  --path-part users \
  --query 'id' --output text)

USERID_RESOURCE=$(aws apigateway create-resource \
  --rest-api-id "$API_ID" \
  --parent-id "$USERS_ID" \
  --path-part '{userId}' \
  --query 'id' --output text)

aws apigateway put-method \
  --rest-api-id "$API_ID" \
  --resource-id "$USERID_RESOURCE" \
  --http-method GET \
  --authorization-type NONE

aws apigateway put-integration \
  --rest-api-id "$API_ID" \
  --resource-id "$USERID_RESOURCE" \
  --http-method GET \
  --type AWS_PROXY \
  --integration-http-method POST \
  --uri "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:user-lookup/invocations"

# REST API has no auto-deploy — every change requires an explicit deployment
aws apigateway create-deployment \
  --rest-api-id "$API_ID" \
  --stage-name prod

Seven commands versus HTTP API's five, and that's before adding auth — REST API has no native JWT authorizer at all. You'd add a Lambda authorizer via create-authorizer --type TOKEN, which is its own Lambda function to write, deploy, and maintain, purely to validate a token that HTTP API checks natively with one --jwt-configuration flag. AUTHORIZATION_TYPE=NONE above is intentionally the simplest case to keep the comparison fair — swapping in Cognito or a Lambda authorizer adds two more commands on the REST API side and zero on the HTTP API side.

That gap is the entire argument for defaulting to HTTP API. Not the price alone — the operational surface. Every additional resource, method, and integration on REST API is something you version, test, and can misconfigure. HTTP API's route-based model has fewer places to get it wrong.

The Feature Gap That Actually Justifies REST API

None of this means REST API is obsolete. It means most projects don't need what it offers. Per AWS's own comparison documentation, REST API supports several things HTTP API structurally cannot do at all:

Feature	REST API	HTTP API
API keys + usage plans	Yes	No
Per-client rate limiting	Yes	No
AWS WAF integration	Yes	No
Request validation (schema)	Yes	No
Private (VPC-only) endpoints	Yes	No
Response caching	Yes	No
Mock integrations	Yes	No
JWT authorizer (native)	No	Yes
Auto-deploying stages	No	Yes
Private integrations via AWS Cloud Map	No	Yes

If you're selling API access to third-party developers and need to issue API keys with per-key quotas, that's REST API, full stop — HTTP API has no equivalent mechanism, not a smaller version of one. Same for WAF: if compliance requires a web application firewall in front of the gateway, REST API is your only option between the two. I've built exactly one REST API in the last two years for a client billing external partners per API key against a usage plan — every other new project defaulted to HTTP API.

Cost at Scale

The sticker prices understate how fast this compounds. At 500 million requests a month:

	HTTP API	REST API
First 300M	$300 (at $1.00/M)	$1,050 (at $3.50/M)
Remaining 200M	$180 (at $0.90/M)	$700
Monthly total	$480	$1,750

That's before data transfer, which is identical on both ($0.09/GB after the first 100 GB). A team that defaults to REST API out of habit on a 500M-request workload is paying an extra $1,270 a month for features it may never touch. Multiply that by however many services in your org made the same default choice and it stops being a rounding error.

Common Mistakes

Mistake 1: Choosing REST API because older tutorials only cover it
Most CLI tutorials predate HTTP API's 2019 launch or were never updated. If a walkthrough uses aws apigateway create-rest-api and never mentions apigatewayv2, it's not wrong, just incomplete — check whether you actually need REST API's feature set before copying it.

Mistake 2: Assuming apigatewayv2 supports API keys
It doesn't, and there's no workaround at the gateway layer. Teams that need lightweight per-client identification on HTTP API end up implementing it themselves — a custom header checked in the Lambda, or a JWT claim — rather than getting it for free the way REST API's usage plans provide it.

Mistake 3: Forgetting the deployment step on REST API
Unlike HTTP API's auto-deploying $default stage, REST API changes are invisible until you run create-deployment. I've debugged more than one "my change isn't showing up" ticket that was just a missing deployment call after a put-integration update.

Mistake 4: Leaving orphaned APIs after testing
Both products bill nothing for an idle API with zero traffic, but Lambda add-permission grants and unused custom domain mappings pile up and become a mess to audit six months later. Clean up as you go.

Teardown

Both products are cheap to tear down completely, and you should — leftover test APIs are how AWS bills quietly creep up.

# HTTP API
aws apigatewayv2 delete-api --api-id "$API_ID"

# REST API
aws apigateway delete-rest-api --rest-api-id "$API_ID"

Full teardown script, including the Lambda permission cleanup, is in the companion repo below.

Production Considerations

Performance: HTTP API adds roughly 6 ms of median gateway overhead; REST API adds roughly 11 ms. At p99, the gap narrows because both are dominated by backend latency, not gateway overhead — don't over-index on this number when choosing.

Security: If you're on HTTP API and need WAF-equivalent protection, put CloudFront with AWS WAF in front of it — HTTP API supports CloudFront origins natively. This is the standard workaround and it works well, but it's an extra piece of infrastructure REST API gives you natively.

Cost: Re-run the math above whenever traffic grows 5-10x. A choice that made sense at 10M requests a month can look very different at 500M.

Monitoring: Both emit CloudWatch metrics. Only REST API emits execution logs and X-Ray traces natively — on HTTP API, instrument tracing inside the Lambda itself if you need request-level tracing.

Full Example: Build-and-Verify Script

The companion repository includes a complete bash script that builds both APIs, verifies each with a live curl, and tears both down. The core verification logic:

#!/usr/bin/env bash
set -euo pipefail

verify_endpoint() {
  local url="$1"
  local label="$2"
  local status
  status=$(curl -s -o /dev/null -w '%{http_code}' "$url")
  if [[ "$status" == "200" ]]; then
    echo "OK   $label -> $status"
  else
    echo "FAIL $label -> $status"
    exit 1
  fi
}

verify_endpoint "https://${HTTP_API_ID}.execute-api.${AWS_REGION}.amazonaws.com/users/usr_42" "HTTP API"
verify_endpoint "https://${REST_API_ID}.execute-api.${AWS_REGION}.amazonaws.com/prod/users/usr_42" "REST API"

Full source with setup, teardown, and verification scripts: GitHub → cloud-apis/amazon-api-gateway-cli/

Conclusion

Default to HTTP API. It's cheaper, has fewer commands to build and maintain, and natively supports JWT auth — the thing most new services actually need. Reach for REST API only when you specifically need API keys with usage plans, WAF, request validation, caching, or private VPC-only endpoints — features HTTP API doesn't have a smaller version of, because it was never built to. The CLI makes this concrete in a way the marketing pages don't: five commands versus seven isn't just fewer keystrokes, it's fewer places for a misconfigured resource or a forgotten deployment to bite you in production.

REST API Design Best Practices: A Field Guide for Backend Developers

Bry — Tue, 07 Jul 2026 15:00:00 +0000

Key Points

Name resources with nouns and plural forms (/users, /orders/{id}), never verbs (/getUser, /createOrder).
Match HTTP methods to their RFC-defined semantics — GET is safe and idempotent, POST is neither, PATCH is partial update.
Return RFC 7807 Problem Details for all error responses — a consistent, machine-readable error shape your consumers can rely on.
Use URL path versioning (/v1/) — it is visible, cacheable, and debuggable without header inspection.
Cursor-based pagination scales to any dataset size; offset-based pagination breaks under concurrent writes.

Introduction

An API that ignores HTTP semantics, uses verbs in URLs, and returns { "error": "something went wrong" } is technically functional. It also generates a steady stream of support tickets, misconfigured clients, and integration bugs that consume engineering time for as long as the API exists.

REST is not a standard — it is a set of architectural constraints described by Roy Fielding in 2000. Most APIs that call themselves RESTful violate several of those constraints and still work fine. The practices in this article are not about philosophical purity. They are about making choices that reduce friction for the developers consuming your API, reduce bugs at integration points, and reduce maintenance burden over a long API lifetime.

I've shipped and maintained REST APIs across enough companies to know that the decisions you make in week one are the ones you're still apologizing for in year three. This article is the set of defaults I'd apply if I were starting a new API today — with a reference implementation that shows all of them working together.

Architecture Overview

Diagram: Request flow from client through API Gateway, token validation, business logic, and data layer.

Resource Design: Naming and Hierarchy

Resources are the nouns in your API. Every URL identifies a resource, not an action.

Rule: Use plural nouns for collections, singular for specific members.

GET    /v1/articles          → list all articles
POST   /v1/articles          → create an article
GET    /v1/articles/{id}     → get one article
PATCH  /v1/articles/{id}     → partially update one article
DELETE /v1/articles/{id}     → delete one article

Never use verbs in paths:

❌ /v1/getArticle
❌ /v1/createArticle
❌ /v1/articles/delete
✓  /v1/articles/{id}   with DELETE method

For sub-resources, express ownership through hierarchy — but stop at two levels. Deeper than two levels signals the resource model needs rethinking.

GET /v1/articles/{id}/comments      ← acceptable
GET /v1/articles/{id}/comments/{cid}/replies/{rid}  ← too deep, model differently

Resource Data Model

HTTP Methods and Status Codes

Method Semantics

Method	Safe	Idempotent	Body	When to use
`GET`	Yes	Yes	No	Fetch a resource or collection. Never mutate.
`POST`	No	No	Yes	Create a new resource. Each call may produce a new resource.
`PUT`	No	Yes	Yes	Replace a resource completely. Must send the full representation.
`PATCH`	No	No	Yes	Partial update. Send only the fields to change.
`DELETE`	No	Yes	No	Remove a resource. Idempotent — deleting twice is not an error.

Safe means the method must not change server state.

Idempotent means calling it N times has the same effect as calling it once.

Use PATCH over PUT for updates unless you genuinely need full replacement. Requiring clients to send the entire resource for a title change is wasteful and error-prone.

Status Codes That Matter

Code	Meaning	When
`200 OK`	Success with body	GET, PATCH, PUT responses
`201 Created`	Resource created	POST success — include `Location` header
`204 No Content`	Success, no body	DELETE success
`400 Bad Request`	Malformed request	Missing required field, invalid format
`401 Unauthorized`	Not authenticated	No token or invalid token
`403 Forbidden`	Authenticated but not allowed	Correct token, wrong permissions
`404 Not Found`	Resource does not exist	ID not in database
`409 Conflict`	State conflict	Duplicate create, optimistic lock failure
`422 Unprocessable Entity`	Valid format, invalid content	Passes JSON parse but fails business validation
`429 Too Many Requests`	Rate limit hit	Include `Retry-After` header
`500 Internal Server Error`	Server bug	Never expose stack traces

Do not return 200 OK with an error payload. A client that checks the status code first — which all good clients do — will miss your error.

Request-Response Sequence

Response Shape: Data and Errors

Success Response

Keep success responses flat when possible. Wrap in a data envelope only when you need top-level metadata alongside the resource (e.g., pagination).

// Single resource — no wrapper needed
{
  "id": "abc123",
  "title": "REST API Design Best Practices",
  "authorId": "usr_789",
  "status": "published",
  "createdAt": "2026-10-01T09:00:00Z",
  "updatedAt": "2026-10-01T09:00:00Z"
}

// Collection — wrapper needed for pagination metadata
{
  "data": [...],
  "pagination": {
    "limit": 20,
    "next_cursor": "abc124"
  }
}

Use ISO 8601 for all timestamps with UTC timezone (Z suffix). Never return Unix epoch integers — they require client-side conversion and obscure the value during debugging.

Error Response — RFC 7807 Problem Details

RFC 7807 defines a standard error response format. Use it. Your consumers can write error handling once and it works across all your endpoints.

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Article Not Found",
  "status": 404,
  "detail": "No article with id 'abc999' exists.",
  "instance": "/v1/articles/abc999"
}

Set Content-Type: application/problem+json on all error responses.

import { Response } from 'express';

function problem(
  res: Response,
  status: number,
  title: string,
  detail: string,
  instance?: string,
): void {
  const body: Record<string, unknown> = {
    type: `https://api.example.com/errors/${status}`,
    title,
    status,
    detail,
  };
  if (instance) body.instance = instance;
  res.status(status).contentType('application/problem+json').json(body);
}

// Usage
problem(res, 404, 'Article Not Found', `No article with id '${id}' exists.`, req.path);

Versioning

You will change your API. Version it from day one.

Strategy	Example	Pros	Cons
URL path	`/v1/articles`	Visible, cacheable, loggable, bookmarkable	URL "leaks" version — semantic purists object
Request header	`API-Version: 2026-01-01`	Clean URLs	Invisible, hard to test in browser, can't cache differently
Query param	`/articles?version=1`	Easy to test	Pollutes query space, gets stripped by some proxies
Accept header	`Accept: application/vnd.api.v2+json`	RFC-compliant content negotiation	Verbose, poor tooling support

Use URL path versioning. You'll hear that it violates REST semantics — typically from people who've never had to track down a versioning bug in production logs where the client was silently sending the wrong header. Visibility in logs, cache keys, and browser testability are real, daily benefits. The semantic purity objection is theoretical.

State Diagram: API Version Lifecycle

Announce deprecation in response headers: Deprecation: true, Sunset: Sat, 01 Jan 2028 00:00:00 GMT.

Pagination and Filtering

Cursor vs Offset

Criteria	Offset (`?page=2&limit=20`)	Cursor (`?cursor=abc&limit=20`)
Performance at scale	Degrades — `OFFSET 1000000` is slow	Constant — indexed seek
Stable under concurrent writes	No — items shift between pages	Yes — cursor anchors position
Seekable to arbitrary page	Yes	No — must walk forward
Implementation complexity	Low	Medium

Use cursor pagination. OFFSET 100000 is a slow table scan dressed up as a query parameter. I've seen this exact pattern take down a read replica during a traffic spike — the query plan looked fine in development on 5,000 rows, then became catastrophic at 2 million under load. Offset pagination is fine for 50-row config lists that never change. For anything that grows or updates frequently, use cursor pagination from day one. Retrofitting it later is painful.

app.get('/v1/articles', (req: Request, res: Response) => {
  const limit = Math.min(parseInt((req.query.limit as string) ?? '20', 10), 100);
  const cursor = req.query.cursor as string | undefined;
  const authorId = req.query.author_id as string | undefined;
  const status = req.query.status as string | undefined;

  let items = Array.from(db.values());
  if (authorId) items = items.filter(a => a.authorId === authorId);
  if (status)   items = items.filter(a => a.status === status);

  let start = 0;
  if (cursor) {
    const idx = items.findIndex(a => a.id === cursor);
    if (idx !== -1) start = idx + 1;
  }

  const page = items.slice(start, start + limit);
  const nextCursor = page.length === limit ? page[page.length - 1].id : null;

  res.json({ data: page, pagination: { limit, next_cursor: nextCursor } });
});

Filtering goes in query parameters. Sorting too:

GET /v1/articles?status=published&author_id=usr_789&sort=-createdAt&limit=20

Convention: prefix - means descending (-created_at = newest first).

Security Fundamentals

Authentication

Pass credentials in the Authorization header. Never in URLs — URLs appear in server logs, browser history, and proxy caches.

# Correct
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/articles

# Wrong — token in logs forever
curl https://api.example.com/v1/articles?token=$TOKEN

Request Authentication Flow

HTTPS Only

Enforce HTTPS at the gateway level. Reject HTTP with 301 Moved Permanently to the HTTPS equivalent. Never accept credentials over plain HTTP.

Rate Limiting Response

When you rate-limit a request, return 429 Too Many Requests with these headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1727780460

Idempotency Keys

POST is not idempotent — calling it twice creates two resources. Networks are unreliable. A client that retries a timed-out POST /v1/orders could create a duplicate charge.

The solution: clients attach a unique Idempotency-Key header. The server stores the response for that key. If the same key arrives again, return the cached response without re-executing the operation.

# First request — creates the article
curl -X POST https://api.example.com/v1/articles \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","content":"...","authorId":"usr_1"}'
# → 201 Created

# Retry with same key (network timeout, client retries)
curl -X POST https://api.example.com/v1/articles \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  ...
# → 201 Created (same response, no second article created)

// Middleware: check and store idempotency keys
// Use Redis with a TTL (e.g., 24 h) in production — Map is in-memory only
const idempotencyStore = new Map<string, { status: number; body: unknown }>();

function withIdempotency(
  handler: (req: Request, res: Response) => void,
): (req: Request, res: Response) => void {
  return (req, res) => {
    const key = req.headers['idempotency-key'] as string | undefined;
    if (key) {
      const cached = idempotencyStore.get(key);
      if (cached) {
        res.status(cached.status).json(cached.body);
        return;
      }
      const originalJson = res.json.bind(res);
      res.json = (body) => {
        idempotencyStore.set(key, { status: res.statusCode, body });
        return originalJson(body);
      };
    }
    handler(req, res);
  };
}

// Apply to any non-idempotent route
app.post('/v1/articles', withIdempotency((req, res) => {
  // ... normal create logic
}));

Idempotency keys matter most for payment, order, and email-send endpoints. Stripe, PayPal, and Shopify all implement this pattern. Your key store needs a TTL — a key that lives forever leaks memory; 24 hours is the Stripe standard.

Common Mistakes

Mistake 1: Verbs in resource names

POST /v1/sendEmail treats the action as the resource. The resource is the email — the action is the HTTP method. POST /v1/emails is correct. If an action genuinely has no resource noun, use a sub-resource: POST /v1/articles/{id}/publish.

Mistake 2: Returning 200 OK for errors

Returning { "success": false, "error": "not found" } with 200 OK means clients must parse and inspect the body on every response to detect failures. HTTP status codes exist precisely to avoid this. Use them.

Mistake 3: Swallowing 404 vs 403

Returning 404 Not Found when the resource exists but the caller lacks access is both a correctness bug and a security vulnerability — you're leaking resource existence to unauthorized callers. The correct response is 403 Forbidden. Return 404 only when the resource genuinely does not exist (or when you deliberately want to hide its existence — which must be an intentional, documented choice, not an accident).

Mistake 4: Offset pagination in high-traffic collections

SELECT * FROM articles ORDER BY created_at LIMIT 20 OFFSET 10000 requires the database to read and discard 10,000 rows. I've debugged production incidents caused by exactly this — the query looks fine on 5,000 rows in development, then becomes a full table scan in disguise at 2 million rows under peak load. Switch to cursor-based pagination: WHERE id > $cursor ORDER BY id LIMIT 20.

Mistake 5: No consistent error shape

An API that returns { "message": "..." } on some errors, { "error": { "code": "...", "description": "..." } } on others, and a plain HTML 500 page on unhandled exceptions forces consumers to write separate error handling for every possible failure mode. Adopt RFC 7807 and return the same shape everywhere — including unhandled 500s.

Full Example: Complete Express TypeScript Implementation

Everything covered above in one runnable file. Copy it, run npm run dev, and use the curl commands below to verify each behavior.

import express, { Request, Response } from 'express';
import { z } from 'zod';
import { randomUUID } from 'crypto';

const app = express();
app.use(express.json());

// Types

interface Article {
  id: string;
  title: string;
  content: string;
  authorId: string;
  status: 'draft' | 'published';
  createdAt: string;
  updatedAt: string;
}

const db = new Map<string, Article>();

// Helpers

function nowIso(): string {
  return new Date().toISOString();
}

function problem(res: Response, status: number, title: string, detail: string, instance?: string): void {
  const body: Record<string, unknown> = {
    type: `https://api.example.com/errors/${status}`,
    title,
    status,
    detail,
  };
  if (instance) body.instance = instance;
  res.status(status).contentType('application/problem+json').json(body);
}

// Validation schemas

const ArticleCreateSchema = z.object({
  title: z.string().min(1),
  content: z.string().min(1),
  authorId: z.string().min(1),
});

const ArticleUpdateSchema = z.object({
  title: z.string().min(1).optional(),
  content: z.string().min(1).optional(),
});

// Routes

// POST /v1/articles — create, 201 + Location header
app.post('/v1/articles', (req: Request, res: Response) => {
  const parsed = ArticleCreateSchema.safeParse(req.body);
  if (!parsed.success) {
    problem(res, 422, 'Validation Error', parsed.error.issues.map(i => i.message).join(', '));
    return;
  }
  const id = randomUUID();
  const ts = nowIso();
  const article: Article = { id, ...parsed.data, status: 'draft', createdAt: ts, updatedAt: ts };
  db.set(id, article);
  res.status(201).setHeader('Location', `/v1/articles/${id}`).json(article);
});

// GET /v1/articles — list with cursor pagination and filtering
app.get('/v1/articles', (req: Request, res: Response) => {
  const limit = Math.min(parseInt((req.query.limit as string) ?? '20', 10), 100);
  const cursor   = req.query.cursor    as string | undefined;
  const authorId = req.query.author_id as string | undefined;
  const status   = req.query.status   as string | undefined;

  let items = Array.from(db.values());
  if (authorId) items = items.filter(a => a.authorId === authorId);
  if (status)   items = items.filter(a => a.status === status);

  let start = 0;
  if (cursor) {
    const idx = items.findIndex(a => a.id === cursor);
    if (idx !== -1) start = idx + 1;
  }

  const page = items.slice(start, start + limit);
  const nextCursor = page.length === limit ? page[page.length - 1].id : null;
  res.json({ data: page, pagination: { limit, next_cursor: nextCursor } });
});

// GET /v1/articles/:id
app.get('/v1/articles/:id', (req: Request, res: Response) => {
  const article = db.get(req.params.id);
  if (!article) { problem(res, 404, 'Article Not Found', `No article with id '${req.params.id}'.`, req.path); return; }
  res.json(article);
});

// PATCH /v1/articles/:id — partial update
app.patch('/v1/articles/:id', (req: Request, res: Response) => {
  const article = db.get(req.params.id);
  if (!article) { problem(res, 404, 'Article Not Found', `No article with id '${req.params.id}'.`, req.path); return; }

  const parsed = ArticleUpdateSchema.safeParse(req.body);
  if (!parsed.success) { problem(res, 422, 'Validation Error', parsed.error.issues.map(i => i.message).join(', ')); return; }

  if (parsed.data.title   !== undefined) article.title   = parsed.data.title;
  if (parsed.data.content !== undefined) article.content = parsed.data.content;
  article.updatedAt = nowIso();
  res.json(article);
});

// POST /v1/articles/:id/publish — action as sub-resource
app.post('/v1/articles/:id/publish', (req: Request, res: Response) => {
  const article = db.get(req.params.id);
  if (!article) { problem(res, 404, 'Article Not Found', `No article with id '${req.params.id}'.`, req.path); return; }
  if (article.status === 'published') { problem(res, 409, 'Already Published', `Article '${req.params.id}' is already published.`, req.path); return; }
  article.status = 'published';
  article.updatedAt = nowIso();
  res.json(article);
});

// DELETE /v1/articles/:id — 204 No Content
app.delete('/v1/articles/:id', (req: Request, res: Response) => {
  if (!db.has(req.params.id)) { problem(res, 404, 'Article Not Found', `No article with id '${req.params.id}'.`, req.path); return; }
  db.delete(req.params.id);
  res.status(204).send();
});

app.listen(3000, () => console.log('API running on http://localhost:3000'));

Run it:

npm install
npm run dev

Test the full cycle:

# Create
curl -s -X POST http://localhost:3000/v1/articles \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","content":"World","authorId":"usr_1"}' | jq

# List with filter
curl -s "http://localhost:3000/v1/articles?author_id=usr_1&limit=5" | jq

# Publish (action as sub-resource)
curl -s -X POST http://localhost:3000/v1/articles/{id}/publish | jq

# Delete — expect 204
curl -s -o /dev/null -w "%{http_code}" -X DELETE http://localhost:3000/v1/articles/{id}

Full source with tests: GitHub link

Conclusion

REST API design is a set of decisions you make once and live with for years. The ones I see cause the most pain aren't exotic — they're the basics: verbs in URLs, inconsistent error shapes, offset pagination on growing datasets, no versioning plan. None of this is new. RFC 7807 has existed since 2016. Cursor pagination predates it by decades.

The reason these mistakes keep appearing in fresh codebases is that nothing stops you from making them. Frameworks don't enforce it. Tutorials skip it. You have to choose these defaults deliberately.

Now you have a reason to.

DEV Community: Bry

Getting Started with the Claude API: Messages, Streaming, and Tool Use

Key Points

Introduction

Setup

Messages API Basics

Model Selection

Streaming Responses

Tool Use (Function Calling)

Define a tool

Handle the round trip

Error Handling and Retries

Cost Management and Prompt Caching

Prompt caching

Common Mistakes

Full Example

State: The Conversation Turn Model

Conclusion

Further Reading

Amazon API Gateway: REST vs HTTP APIs, Explained via the AWS CLI

Key Points

Prerequisites

Introduction

Two Products, Not Two Versions

Building the Same Endpoint on HTTP API

Building the Same Endpoint on REST API

The Feature Gap That Actually Justifies REST API

Cost at Scale

Common Mistakes

Teardown

Production Considerations

Full Example: Build-and-Verify Script

Conclusion

Further Reading

REST API Design Best Practices: A Field Guide for Backend Developers

Key Points

Introduction

Architecture Overview

Resource Design: Naming and Hierarchy

Resource Data Model

HTTP Methods and Status Codes

Method Semantics

Status Codes That Matter

Request-Response Sequence

Response Shape: Data and Errors

Success Response

Error Response — RFC 7807 Problem Details

Versioning

State Diagram: API Version Lifecycle

Pagination and Filtering

Cursor vs Offset

Security Fundamentals

Authentication

Request Authentication Flow

HTTPS Only

Rate Limiting Response

Idempotency Keys

Common Mistakes

Full Example: Complete Express TypeScript Implementation

Conclusion

Further Reading