API Design

Core Principles

• Contract-First — Define API spec before implementation
• OpenAPI 3.2 — Use OpenAPI for REST API documentation
• URL Versioning — Version in path /v1/, with Sunset headers
• Idempotency — PUT/DELETE must be idempotent, POST uses Idempotency-Key
• Cursor Pagination — Avoid offset-based pagination
• RFC 7807 Errors — Standard Problem Details format
• No backwards compatibility — Delete, don't deprecate

Quick Reference

When to Use What