An API is a long-term contract with everyone who builds on your platform. These ten principles guide the APIs we design and maintain for our clients.
1. Design Around Resources, Not Actions
Model your API around clear nouns such as customers, invoices, or devices. Predictable resource paths make an API easier to learn and far easier to extend later.
2. Be Consistent Everywhere
Use one naming convention, one date format, and one error shape across every endpoint. Consistency removes guesswork and reduces integration support requests.
3. Version From Day One
Publish your first release as v1. Versioning costs nothing at the start and gives you room to make breaking changes without stranding existing integrations.
4. Return Useful Errors
Pair the correct HTTP status code with a machine-readable error code and a human-readable message. Callers should never have to parse prose to handle a failure.
5. Paginate Every Collection
Any list that can grow must be paginated, ideally with cursors. Unbounded responses are the most common cause of slow endpoints as a dataset matures.
6. Validate Input at the Boundary
Validate and coerce every request payload before it reaches your business logic. Schema validation catches bad data early and doubles as living documentation.
7. Make Writes Idempotent
Support idempotency keys on create operations so a retried request after a timeout does not produce duplicate records.
8. Rate Limit and Communicate Limits
Protect the service with sensible limits and return the remaining quota in response headers so clients can back off gracefully.
9. Instrument Before You Scale
Log structured request metrics and trace slow paths. You cannot optimise what you cannot measure, and load problems rarely appear where you expect them.
10. Document With Real Examples
Every endpoint deserves a copy-and-paste request and a realistic response. Good examples shorten integration time more than any amount of reference prose.
Conclusion
Scalable APIs are the result of disciplined, boring decisions applied consistently. Get the fundamentals right and growth becomes an engineering detail rather than a crisis.