Every article tagged API Design, in one place.
Showing 8 articles
A well-designed REST API is predictable: once a developer has used one endpoint, they can guess how the others work. These conventions get you most of the way there. URLs name resources, not actions GET /orders list orders POST /orders create an order GET /ord...
Any list endpoint needs pagination. The two main approaches behave very differently on large or fast-changing data. Offset pagination GET /articles?page=3&per_page=20 SELECT * FROM articles ORDER BY published_at DESC LIMIT 20 OFFSET 40; Pros: simple, lets user...
Once other people depend on your API, every change can break someone. Versioning gives you room to evolve without surprises. First: avoid breaking changes Usually safe (additive): Adding a new endpoint. Adding an optional request field. Adding a field to a res...
A client sends POST /payments , the network times out, and it retries. Did the first request succeed? Without protection, the customer may be charged twice. Idempotency keys make retries safe. The contract POST /payments Idempotency-Key: 7f3b2c1e-9a4d-4e8b-a1f...
Every API needs an error format, and many invent their own. Problem Details (RFC 9457, which replaced RFC 7807) is a standard JSON shape for HTTP API errors that clients and tools already understand. The format HTTP/1.1 403 Forbidden Content-Type: application/...
GraphQL and REST both work well. The right choice depends on your clients, your data and your team, not on which one is newer. The core difference With REST, the server decides the shape of each endpoint's response. With GraphQL, the client asks for exactly th...
OpenAPI (formerly Swagger) is a standard, machine-readable description of a REST API. One spec file can produce interactive docs, client SDKs, mock servers and request validation. A minimal spec openapi: 3.1.0 info: title: Orders API version: 1.0.0 servers: -...
Rate limits protect your API from abuse, runaway scripts and accidental traffic spikes, and keep things fair between customers. Common algorithms Fixed window - count requests per calendar minute. Simple, but allows bursts at window edges (100 at 12:00:59 and...
