REST API Design

Language-agnostic REST API design guidance. Covers the contract — what a well-designed API looks like. Implementation skills (Rust, TypeScript) handle the how.

Based on Google API Design Guide (AIP system), Microsoft Azure REST API Guidelines, Zalando RESTful API Guidelines, Stripe API design patterns, RFC 9457 (Problem Details), and OWASP API Security Top 10 (2023).

1. Design Philosophy

APIs are user interfaces for developers. Design for the developer who has never read your docs.

• Principle of least surprise — every endpoint should behave the way a developer expects before reading the docs
• Consistency over cleverness — identical patterns across all endpoints; same naming, same error shape, same pagination, same auth
• Pit of success — make the right thing easy, the wrong thing hard. Sensible defaults, forgiving input, strict output
• API as product (Zalando) — treat every API as a product with users, lifecycle, and quality standards. Peer review API designs before implementation
• Progressive complexity (Stripe) — simple integrations work in a few lines. Advanced features layer on without rewriting the basic integration
• Resource-oriented design (Google) — model entities as resources with standard operations. Standard methods (CRUD) are predictable; custom methods are the escape hatch
• Postel's Law (Zalando) — be liberal in what you accept, be conservative in what you send. Trim whitespace, normalize case, accept optional fields gracefully. Return strict, well-defined shapes