EXPLAINER

REST APIs for Application Development

REST APIs expose resources over HTTP using methods like GET, POST, PUT and DELETE, usually with JSON bodies and status codes that tell you whether the call worked.

Short answer: REST is a common HTTP style: resources, methods, status codes, JSON bodies. Model and SaaS APIs you call from agents often follow it.

What is it?

REST is a widely used way to design HTTP APIs. You identify resources with URLs (/v1/conversations/123), use methods to read or change them, send/receive JSON, and rely on status codes (200, 201, 400, 401, 404, 429, 500). Many AI vendor endpoints are REST-like even when they also offer streaming.

Why it matters

Agent tools and backends spend their lives calling REST APIs. Understanding methods and status codes prevents treating every failure as "the model broke".

How to do it

  1. Read the OpenAPI/docs for paths and schemas.
  2. Authenticate as documented (API Authentication: Keys, Sessions and OAuth).
  3. Prefer idempotent GET/PUT patterns where the API offers them.
  4. Check status codes before parsing bodies as success.
  5. Honour Retry-After on 429 when present.
  6. Validate JSON (How to Validate JSON).

When wrapping REST for agents, expose task-level tools rather than one tool per endpoint (MCP vs API: What's the Difference?, Agent Tools: How AI Agents Take Actions).

Example

POST /v1/chat/completions HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: application/json

{"model":"your-model-id","messages":[{"role":"user","content":"Hi"}]}

Non-2xx responses should be handled as errors even if the body contains JSON.

When to use it

Use REST (or REST-like HTTP) for app backends and SaaS integrations. Consider GraphQL/gRPC when your stack already standardises on them — the auth and validation lessons still apply.

Practical notes

Design tips for your own REST AI backend: use nouns for resources ('/conversations', '/messages'), keep actions that do not fit CRUD as carefully named POSTs ('/conversations/{id}/cancel-stream'), and return problem-details or a small error object consistently. Pagination should be explicit for message history. Idempotency headers help when clients retry after network failures. For agent tools wrapping third-party REST, translate HTTP errors into short strings the model can act on ("not found", "forbidden", "rate limited") without dumping HTML error pages into the context window. See API Authentication: Keys, Sessions and OAuth for keys and OAuth and How to Validate JSON for bodies. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern.

Common mistakes

  • Ignoring status codes because "there was a body".
  • Caching authenticated GET responses incorrectly.
  • Mapping every REST endpoint 1:1 to an agent tool.