API Design — What Claude Gets Wrong

You write endpoints that return bare data, use inconsistent error shapes, skip pagination on lists, and leak database models to clients. Each endpoint looks different. Clients need N parsers for N endpoints.

The Six Rules

1. Consistent response envelope — every endpoint, same shape
2. Proper HTTP status codes — not just 200 and 500
3. Cursor-based pagination — on every list endpoint
4. Input validation — beyond deserialization
5. Structured error responses — with codes, not just messages
6. DTO separation — API response != database row

Response Envelope