api-design

REST API Design Guide

Overview

Design stable, well-documented REST APIs that are predictable and hard to misuse. Good APIs make the right operations easy and incorrect usage hard. This guide defines conventions for resource modeling, endpoint hierarchies, standard HTTP methods, payload schemas, error formats, and idempotency.

When to Use

• Designing new REST API endpoints or resources
• Defining request and response contracts between clients and the backend
• Establishing data schemas and models that inform the API shape
• Versioning, extending, or refactoring existing REST endpoints

---

1. Core Principles

Hyrum's Law

With a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody, regardless of what you promise in the contract.

Every public behavior — including undocumented quirks, error message phrasing, response headers, timing, and ordering — becomes a de facto contract once clients depend on it.

• Be intentional about what you expose: Every observable field or header is a commitment.
• Don't leak implementation details: Never expose internal database column names, raw SQL errors, or stack traces.
• Plan for deprecation at design time: Phased deprecation is required before removing fields or endpoints.
• Tests alone are not enough: Changes that pass unit tests can still break consumers relying on subtle undocumented behaviors.

The One-Version Rule

Avoid forcing consumers to navigate multiple diverging versions of the same API. Design endpoints to be backward-compatible and additive rather than repeatedly forking major versions.

Contract First

Define the endpoint specifications (HTTP method, URL path, request body, query parameters, status codes, and response schemas) before implementing internal logic.

POST   /v2/todos              → Create a todo (201 Created)
GET    /v2/todos              → List todos with pagination (200 OK)
GET    /v2/todos/:id          → Retrieve a todo (200 OK)
PATCH  /v2/todos/:id          → Partial update (200 OK)
DELETE /v2/todos/:id          → Delete a todo (204 No Content)