APIs & tool/function calling

HTTP & REST, the parts that matter

An API is a contract over HTTP. Two properties drive everything downstream:

• Safe = no server state changes (GET, HEAD).
• Idempotent = N identical requests have the same effect as one. GET, PUT, DELETE are idempotent; POST is not (it creates/executes). That single fact is why payments and webhooks need idempotency keys.

Status codes you must know cold: 401 = unauthenticated, 403 = authenticated but not allowed, 404 not found, 409 conflict, 422 validation failed, 429 too many requests (carries Retry-After), 500 server error, 502/503/504 upstream/unavailable/timeout. Mental model: 4xx = client's fault, 5xx = server's fault — this drives your retry logic later.

REST means resource-oriented URLs (nouns: /problems/42/submissions, not /getSubmission), statelessness (each request self-contained), and JSON representations. Note JSON has no native date or int64 type — send timestamps as ISO-8601 strings and big IDs as strings.

How an LLM calls your systems (the tool-calling loop)

Teach this as a strict sequence — candidates fumble the ordering:

1. You expose tools as JSON-Schema definitions: each has a name, a description (this is a prompt — the model reads it to decide when to call), and an input schema (types, required fields, enums).
2. The model never executes anything. It emits a structured request to call — Anthropic returns a tool_use block with stop_reason: "tool_use"; OpenAI returns tool_calls.
3. Your code executes the real function, then returns the result back into the conversation (a referencing the call id).