An API is a promise to every consumer that builds against it, and breaking promises is the most expensive thing an API team can do. Good design, then, is mostly about making promises you can keep: predictable shapes, honest errors, and evolution paths that do not strand your users.
Predictability beats cleverness
- Model resources as plural nouns and let HTTP verbs carry the action: GET /invoices, POST /invoices, not POST /createInvoice.
- Pick one casing convention and one timestamp format (ISO 8601, UTC) and never deviate.
- Use status codes for what they mean: 400 for bad input, 401 versus 403 for who-are-you versus not-allowed, 404 for absent, 422 for well-formed but invalid.
- Return errors as structured objects with a machine-readable code, a human-readable message, and the field at fault, because someone will build UI on your errors.
Design for the day after launch
Paginate every collection from day one; adding pagination later breaks everyone. Cursor-based pagination stays correct when data changes underneath the reader, which offset-based never quite does. Make write operations idempotent with client-supplied keys, since every network eventually retries. Rate limit from the start and say so in response headers, because the alternative is discovering your limits during someone's incident.
Version reluctantly, evolve deliberately
Additive changes, new fields, new endpoints, new optional parameters, need no version bump, and consumers should be told to tolerate unknown fields. Breaking changes deserve a coarse version, a migration guide, and a long, honest deprecation window with usage monitoring so you know who has not moved.
Before shipping, write the documentation and build a small client against it. Every confusing name and awkward flow surfaces immediately, while renaming things is still free. The API you would enjoy consuming is the one worth publishing.