Software Engineering Foundations for Claude Integration

1. REST APIs and JSON

Every request to Claude travels over a REST API using standard HTTP methods and URLs, exchanging data as JSON. REST treats everything the server exposes as a resource addressed by a URL, acted on with a handful of universal verbs.

A minimal JSON request is a top-level object with typed fields: model selects the Claude model, max_tokens caps the response length (and cost), and messages is an ordered array of turns, each with a role (user or assistant) and content. The response is likewise JSON — a content array plus metadata such as token usage and a stop reason.

Because REST inherits HTTP's stateless property, each request must carry everything the server needs — which is why you resend the entire conversation history on every turn rather than relying on the server to remember it.

Three headers matter for a basic call:

The API key is a bearer credential: anyone who holds it can spend from your account. It belongs in an environment variable (ANTHROPIC_API_KEY), never hardcoded and never committed to version control.

Figure 6.1: Stateless request/response flow for a Messages API call

2. Asynchronous Programming

A call to Claude is a network round-trip that can take seconds. If your program simply blocks and waits, it wastes time it could spend serving other users or issuing more requests. async/await lets you write non-blocking code that reads like ordinary sequential code: you mark a function async and await where you need the result, freeing the runtime to run other tasks meanwhile. Anthropic's Python SDK provides AsyncAnthropic (built on httpx); TypeScript calls are promise-based, so await is all you need.

The real payoff is concurrency: firing off many requests that overlap in flight rather than running strictly one after another. Since most of each request's duration is spent waiting on the network, that wait overlaps for free — summarizing 20 documents concurrently (e.g., with Python's asyncio.gather) can be dramatically faster than looping sequentially. The catch: concurrency raises the risk of hitting rate limits, the per-minute caps Anthropic enforces. The guidance is to ramp traffic up gradually and keep usage patterns consistent; sudden bursts produce 429 errors and can trip acceleration limits. Effective concurrency means bounding how many requests are in flight, not launching everything at once.

Websockets vs. SSE — a nuance the exam tests

A websocket is a persistent, bidirectional connection where client and server can send messages at any time — well suited to live multiplayer or collaborative editors. It is tempting to assume Claude streaming uses websockets. It does not. Anthropic's SDKs stream via Server-Sent Events (SSE), a simpler, unidirectional mechanism where the server pushes a sequence of events over a single long-lived HTTP response. The client makes one request; the server streams incremental chunks back down that one connection — a one-way flow, not the two-way conversation a websocket is built for.

One consequence of SSE: because the HTTP status is 200 the moment the stream opens, an error can occur after that success code. Mid-stream errors arrive as SSE error events and do not follow the standard status-code error mechanism, so streaming code must watch for error events within the stream, not just the initial response status.

3. SDKs That Wrap REST

You could hand-build every HTTP request, header, and JSON parse yourself. In practice you use a client SDK — a language-specific library that wraps REST behind idiomatic, typed functions. The Python SDK (anthropic) ships both a synchronous Anthropic client and an async AsyncAnthropic, both on httpx, typed via Pydantic. The TypeScript SDK (@anthropic-ai/sdk) auto-reads the key from ANTHROPIC_API_KEY and runs on Node.js, Deno, Bun, and browsers.

The SDK's central trick is to turn the raw POST /v1/messages into a single typed method call. When you invoke client.messages.create(...), the SDK serializes your typed parameters to JSON, adds the required headers, sends the POST, and deserializes the response into a typed Message — everything from Section 1 handled for you. Streaming is likewise abstracted over SSE. Every response also carries a unique request-id (exposed as _request_id), invaluable for debugging.

Figure 6.2: How the SDK wraps the raw REST call

Error handling and retries

Claude returns errors as JSON with a top-level error object (a type and message) plus a request_id. The status-code taxonomy is worth memorizing:

A distinction the exam loves: 429 vs. 529. A 429 means your account exceeded its own per-minute limits — the fix is to slow your own traffic. A 529 means Anthropic's servers are temporarily at capacity for everyone, independent of your usage — the fix is to back off and retry, possibly with failover. Same "too busy" feeling, different cause and remedy.

The SDKs make much of this automatic: they retry transient failures — connection errors, 429s, and 5xx — using exponential backoff, twice by default, honoring the retry-after header when present. Exponential backoff means each retry waits longer than the last (roughly doubling). If you hand-roll retries, respect retry-after first, then reset-header math, then jittered exponential backoff — the jitter (small random delay) breaks the "thundering herd." Finally, the SDKs raise typed exceptions (a 404 becomes anthropic.NotFoundError); catch these most-specific-first rather than string-matching.

Figure 6.3: SDK retry and exponential-backoff state flow

4. Engineering Practices and the SDLC

Version control (Git in practice) records the full change history of a codebase. The distinctive move for Claude integrations is to treat prompts as code: prompt templates are development artifacts, so they belong in the repo — typically in a prompts/ directory, organized by feature, one prompt per file. This makes a prompt change reviewable, diffable, revertible, and testable exactly like source code. Concrete habits: write meaningful commit messages (what and why), use branches to explore prompt/model variations, and use Git as a state log with checkpoints so you can cleanly revert an AI-generated change that does not pan out.

A non-negotiable: never commit secrets. Keep ANTHROPIC_API_KEY in environment variables and add .env to .gitignore. The SDKs read the key from the environment by default, which makes this painless.

Code review should cover the LLM-specific concerns alongside the usual ones: correct handling of the full status-code taxonomy (401/403/429/500/529), retry and backoff configuration, timeout handling, no hardcoded secrets, prompt-injection and untrusted-input handling, and cost/token controls such as max_tokens and batching. Claude can also participate: running the SDK or CLI in non-interactive mode lets you wire it into CI pipelines and pre-commit hooks — for example, feeding a diff to a structured security-review prompt to flag vulnerabilities before merge.

Refactoring behind a thin typed layer

Refactoring improves internal structure without changing external behavior. The guiding principle is to isolate the integration behind a thin, well-typed abstraction layer, so model IDs, prompts, retry policy, and timeouts are centralized and swappable. The analogy is a building's electrical panel: route everything through one panel with labeled breakers, so changing a fuse — swapping claude-sonnet-5 for a newer model, tightening a timeout, bumping the retry count — touches one place, not fifty. Small-scale refactoring is local (rename a prompt file, extract a helper); large-scale refactoring restructures whole modules (introduce the central client wrapper, move inline prompts to versioned files, standardize typed-exception handling).

Figure 6.4: SDLC integration pipeline for a Claude feature