Core Code
Core Code Modern Dev Handbook

Statelessness

Why stateless APIs scale better and how to apply it.
On this page

Stateless requests

In a stateless API, every request includes the information the server needs to understand and process it. The server does not rely on per-client session state stored in memory between requests.

Why statelessness is production-friendly

  • Easier horizontal scaling (any server can handle any request)
  • Better reliability (a server restart does not break sessions)
  • Simpler caching and observability
  • Works well with gateways, CDNs, and load balancers

What belongs in a request

  • Authentication (Authorization header)
  • All required parameters (path, query, body)
  • Client context if needed (locale, version, request-id)

Example: stateless auth

GET /api/orders?limit=20
Authorization: Bearer <token>
Accept: application/json

What statelessness does not mean

  • It does not mean “no database” (servers keep shared state in DB/services).
  • It does not forbid caching (it enables it).
  • It does not forbid long workflows (you model them as resources).

Common mistakes

  • Keeping user session in server memory for API clients
  • Requiring “sticky sessions” to make the API work
  • Hidden state that breaks when requests hit different nodes

Checklist

  • Any node can process any request.
  • No in-memory per-user server session is required for correctness.
  • Auth and required context are included per request.
Content Negotiation →