# API Endpoint Design

REST endpoint conventions that make APIs predictable.

## Rules

1. **Nouns for resources, verbs are HTTP.** `GET /users`, `POST /orders`, `DELETE /sessions/id`. Never `POST /createUser`. The method is the verb.

2. **Consistent response shape.** Every endpoint returns `{ data, error }` or `{ data, meta }`. Never sometimes-wrap-sometimes-don't. Consumers should not need to inspect the shape before parsing.

3. **Pagination is default.** Any list endpoint paginates from day one. `?page=1&limit=25`. Even if the dataset is small today. It won't be tomorrow.

4. **Status codes tell the truth.** 200 for success, 201 for created, 204 for deleted. 400 for bad input, 401 for unauthenticated, 403 for unauthorized, 404 for not found, 409 for conflict, 422 for validation failure, 429 for rate limited, 500 for server error. No 200-with-error-body.

5. **Version in the URL.** `/v1/users`. Not in a header. The URL is the contract. It should be visible, cacheable, and breakable in isolation.

6. **Document every endpoint with an example.** Request body, response body, error cases. If it's not documented, it doesn't exist.

## What This Replaces

Ad-hoc endpoint design where every route is a special snowflake.