Designing an API Other Systems Can Rely On

Consistency matters more than elegance

An API that is predictable is easier to consume than one that is clever. Same envelope shape, same error format, same naming conventions, same pagination approach across every endpoint.

Consumers write code against your patterns. Inconsistency means every endpoint has to be read individually.

What to get right

1. Status codes that mean what they say — not 200 with an error in the body
2. Error responses with a consistent shape and a machine-readable code
3. Pagination on every collection endpoint, from the start
4. Authentication appropriate to the consumer — tokens for services, sessions for browsers
5. Rate limiting, with clear headers about the limit and remaining quota

Returning 200 with an error message in the body is the most common API design mistake. Every consumer then has to parse the body to know whether it worked.

Version before you need to

Decide the versioning approach before the first external consumer. Adding versioning after the fact means either breaking existing consumers or maintaining an unversioned path forever.

A path prefix is the simplest approach and is adequate for most business APIs.

Document it properly

• Every endpoint, with example requests and responses
• Every error code and what causes it
• Authentication, with a working example
• Rate limits, explicitly
• Generated from the code where possible, so it stays current

Think about the consumer

Whoever writes against your API cannot see your database schema and does not know your internal terminology. Expose concepts they understand rather than your table structure.

The test is whether someone could build against it from the documentation alone, without asking you anything.

Frequently asked questions