REST APIs and JSON for Claude

In short: Claude is reached over an HTTP REST endpoint that accepts and returns JSON payloads. Client SDKs wrap that REST API and handle auth headers, serialization, and retries, but they do not remove the need to handle HTTP errors or to validate and defensively parse the JSON the model itself produces.

Claude is a REST API that speaks JSON

At the lowest level, integrating Claude is an exercise in ordinary web-service engineering. Claude is reached over an HTTP REST endpoint: your application sends an HTTP request whose body is a JSON payload describing the conversation, and the endpoint returns an HTTP response whose body is a JSON payload containing the assistant's answer. There is no magic transport and no special protocol. If you can make an authenticated HTTP POST and parse a JSON body, you can call Claude.

This framing matters for the Claude Certified Developer - Foundations (CCDV-F) exam because it grounds everything else in software-engineering fundamentals you already know. The request carries headers (including authentication) and a JSON body; the response carries a status code and a JSON body. All the higher-level behaviour, the request-response cycle, tool use, streaming, is layered on top of this plain REST-over-JSON foundation, which is why task statement 2.4 treats REST and JSON as the entry point to building Claude applications.

REST and JSON integration: The practice of calling Claude over its HTTP REST endpoint, sending and receiving JSON payloads. Client SDKs wrap this transport and handle auth, serialization, and retries, while the application still owns HTTP error handling and validation of model-generated JSON.

What the SDK does, and what it does not

Most teams do not hand-write HTTP calls; they use a client SDK. The SDK wraps the REST API and takes over the repetitive plumbing: attaching the authentication header on every request, serializing your request object into the JSON body and deserializing the JSON response back into typed objects, and retrying certain transient failures automatically. This is a real convenience, and it is why an SDK integration reads as a clean method call rather than a pile of HTTP boilerplate.

But the SDK's job is bounded. It abstracts the transport; it does not abstract reality. Network calls still fail, rate limits still bite, servers still occasionally return errors, and, crucially, the JSON the model writes inside its response is still just text the model produced and can be wrong. The two exam traps for this knowledge point both come from over-trusting the SDK: assuming it removes error handling, and assuming it makes model output safe. It does neither.

HTTP + JSON

the actual transport under every call

SDK wraps it

auth headers, serialization, retries

you still own

HTTP errors and model-JSON validation

Trap one: the SDK does not remove HTTP error handling

The first trap is assuming the SDK removes the need to handle HTTP errors and malformed JSON. It does not. Even with a well-behaved SDK, a call can fail: the request can be rate limited, the service can be temporarily overloaded, a request can time out, authentication can be rejected, or the server can return an error. The SDK surfaces these as exceptions or error results, and retries only cover a subset of transient cases with a finite number of attempts. If you write code that assumes every call returns a valid response, the first rate-limit spike or timeout takes your application down.

Robust integration therefore handles errors at the call boundary: catch the SDK's error types, distinguish retryable failures (rate limits, transient server errors) from terminal ones (bad request, invalid auth), and degrade gracefully rather than crashing. This is the same guard-clause discipline you would apply to any external HTTP dependency, and it pairs naturally with asynchronous programming, where bounded concurrency and backoff on errors keep a fleet of calls inside the rate limits.

Misconception

I use the official SDK, so I do not need to write error handling; the SDK guarantees every call succeeds.

What's actually true

The SDK handles auth, serialization, and a bounded set of automatic retries, but calls can still fail with rate-limit, timeout, overloaded, invalid-auth, or server errors that surface as exceptions. Your code must catch and handle them; the SDK reduces boilerplate, it does not make failure impossible.

Trap two: never trust model-generated JSON blindly

The second trap is trusting model-generated JSON without validation before use. This is a distinct point from HTTP-level JSON. The response envelope the API returns is well-formed JSON that the SDK parses reliably. But when you ask the model to produce JSON, say, to return a structured record your code will consume, that JSON is content the model generated, and generated content can be malformed, miss a required field, include an extra field, or carry a value outside the range you expected. The SDK cannot validate it for you, because it has no idea what shape you needed.

So robust integration validates and defensively parses the JSON the model produces. Parse it inside a try/catch rather than assuming it parses; validate it against the schema you expected before acting on it; and decide what to do when it fails, retry, repair, or reject. This defensive posture is the same idea as content boundaries and schema design: you specify the shape you want and then verify you actually got it, rather than letting unvalidated model output flow straight into your business logic.

Misconception

I asked Claude to reply with JSON matching my schema, so I can parse the response and use the fields directly.

What's actually true

Model-generated JSON is produced text and can be malformed or miss required fields. Parse it defensively inside error handling, validate it against your expected schema, and decide how to recover on failure before your code acts on any value.

Where the SDK ends and your responsibility begins

Loading diagram...

The SDK owns the transport; the application still owns HTTP error handling and validation of any JSON the model writes.

Worked example

A pipeline asks Claude to extract an invoice into a JSON object with fields amount, currency, and due_date, then writes it to a database.

The first version calls the model through the SDK, takes the text of the response, runs the language's JSON parser on it, and inserts the result straight into the database. It works in testing. In production it fails two ways. First, during a traffic spike some calls are rate limited; the SDK's automatic retries are exhausted and it raises, but the code has no error handling, so the worker crashes. Second, on a few malformed invoices the model returns JSON missing the currency field, or wraps the object in an apologetic sentence so the raw text is not valid JSON at all; the parser throws or the database write inserts a null where a currency was required.

The hardened version fixes both. Around the SDK call it catches the SDK's error types, retries transient failures with backoff, and routes terminal errors to a dead-letter queue instead of crashing. Around the model output it parses defensively inside a try/catch, validates the parsed object against the expected schema, amount is a number, currency is one of the known codes, due_date is a valid date, and only writes rows that pass. Invoices that fail validation are flagged for review rather than silently corrupting the table. Same SDK, same model, but now the integration treats both the HTTP boundary and the model output as things that can fail, which is exactly what the exam expects a developer to do.

How this is tested on the exam

Domain 2 questions on this knowledge point reward developers who know the boundary of the SDK. Expect a scenario where an integration "using the official SDK" falls over under load or on bad input, and you must identify that the SDK does not remove the need to handle HTTP errors, or that unvalidated model-generated JSON flowed straight into downstream code. The correct answer is almost never "the SDK is broken" and almost always "the application skipped a responsibility the SDK never claimed to own."

Hold the layering in mind: Claude is REST over JSON, the SDK wraps that transport and handles auth, serialization, and retries, and you still own HTTP error handling and validation of any JSON the model produces. Those facts, plus the habit of asking "what can fail here that the SDK does not cover," carry you through the questions and set up the rest of task statement 2.4, where asynchronous programming and version control and code review build on this same integration foundation.

Check your understanding

A developer integrates Claude with the official SDK and asks it to return a JSON object their code parses and stores. Under load the service starts crashing, and occasionally it stores records with missing fields. Which two responsibilities did the integration skip?

Watch and learn

Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.

No videos curated for this concept yet

We are still curating the best official and community videos for this topic.

References & primary sources

Adaptive study

Master this concept with Archie

Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.

Start studying

REST APIs and JSON for Claude Integration on the Developer Exam