An API can work perfectly and still be badly designed. This is the fact that makes API quality so difficult for a founder or CTO to evaluate early, because the signal you would naturally rely on, does it work, tells you almost nothing about whether it will keep working as the product grows.
A poorly designed API and a well-designed one both return the correct data in the early stages. Both pass their tests. Both support the current mobile app and the current web client without complaint. The difference between them is invisible until specific pressures arrive: a third consumer that was never anticipated, a scale of traffic the original design did not account for, a new feature that needs data the API was never structured to provide efficiently. By the time those pressures arrive, the API has usually already been built on top of by enough other systems that changing it is no longer a simple fix. It is a breaking change with a migration cost attached.
This post is about how to evaluate API design before that moment arrives, when the cost of changing course is still low. It is written to be useful whether you can read the code yourself or whether you need to have this conversation with a technical lead who can.
A poorly designed API and a well-designed one both work fine in the early stages. The difference only becomes visible under pressure, and by then it is a migration, not a fix.
WHY THIS IS HARD TO EVALUATE FROM THE OUTSIDE
Unlike a user interface, where a non-technical person can form a reasonable opinion by simply using the product, an API has no interface a founder can directly experience. It is consumed by other software, not by people, which means its quality is invisible unless you specifically go looking for it or until it fails in a way that is visible downstream, a mobile app that behaves strangely, a feature that takes far longer to build than it should have, an integration that breaks unexpectedly when a new client is added.
This invisibility is exactly why API design quality is one of the most underexamined aspects of a technical asset. Founders review the user experience constantly, because they can. They rarely review the API, because they cannot without specific effort, and by the time an API problem surfaces as a business problem, it usually presents as something else: a feature that is taking three times longer than estimated, a mobile app team that is blocked waiting on backend changes, an integration partner who cannot get the data format they need.
THE SIGNALS OF A WELL-DESIGNED API
Resources are modelled around what consumers need, not around the database schema
A common and consequential mistake is designing an API that mirrors the database structure directly rather than the actual needs of the applications consuming it. This produces endpoints that are technically accurate but require the consuming application to make multiple calls and stitch data together itself, which pushes complexity into every client that uses the API rather than solving it once, centrally, where it belongs.
// Database-mirrored: forces the client to do the work
GET /users/42
GET /users/42/orders
GET /orders/103/items
// Consumer-oriented: one call, shaped for the actual use case
GET /users/42/dashboard
// returns user info, recent orders, and order summaries together
A well-designed API asks what the consuming application actually needs to display or act on, and shapes the response around that. This is not always fewer endpoints. It is endpoints that map to real use cases rather than database tables, which is a meaningfully different design decision that compounds in value as more consumers and more features are added.
Versioning exists before it is needed
An API that has no versioning strategy is an API that cannot change without breaking every consumer simultaneously. This is fine for the first few months when there is one consumer and the team controls both sides of every change. It becomes a serious constraint the moment a second consumer exists, particularly an external one that the team does not control, such as a partner integration or a public API consumer.
A well-designed API establishes a versioning approach, whether through URL versioning, header-based versioning, or a similar mechanism, before it is strictly necessary. This is one of the clearest signals of design maturity because it requires the team to think about the future consequences of present-day decisions rather than solving only for what is needed right now.
Errors are structured and predictable
The quality of an API error response is one of the most reliable indicators of overall API design quality, because error handling is exactly the kind of unglamorous work that gets skipped when a team is optimising for speed. A well-designed API returns errors in a consistent, structured format across every endpoint, with a clear error code, a human-readable message, and enough detail for the consuming application to respond appropriately.
// Poor: inconsistent, unstructured, unhelpful
{ "error": "failed" }
// Well designed: structured and actionable
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Email address is already in use",
"field": "email"
}
}
An API where every endpoint returns errors differently, some with codes, some without, some with generic messages, some with specific ones, is an API that has been built incrementally without a consistent design discipline applied across it. That inconsistency is a strong signal of broader design debt throughout the system, not just in error handling specifically.
Authentication and authorisation are handled centrally, not per endpoint
In a well-designed API, the logic that determines who is allowed to access a resource lives in one place and is applied consistently. In a poorly designed one, that logic is scattered across individual endpoint implementations, which means it is easy for a new endpoint to be added without the same authorisation checks as the rest of the system, creating a security gap that is invisible until it is discovered, sometimes by an attacker rather than the team.
A useful diagnostic question here: if a new permission rule needed to be added today, such as restricting a certain action to admin users only, would that require a change in one place or in every endpoint that touches the relevant resource? The answer reveals whether authorisation was designed as a system or accumulated as a series of individual decisions.
If a new permission rule required changing every endpoint individually rather than one central place, authorisation was never designed. It accumulated.
Documentation exists and reflects reality
An API without documentation is not automatically badly designed, but it is much harder to evaluate, and the absence of documentation is often correlated with the absence of the design discipline that produces good documentation in the first place. Teams that think carefully about how an API should be consumed tend to document it as a natural extension of that thinking. Teams that build an API reactively, endpoint by endpoint, in response to immediate feature needs, tend not to.
More telling than the presence of documentation is whether it matches what the API actually does. Documentation that has drifted from the real behaviour of the API, describing parameters that no longer exist or omitting ones that were added later, is a signal that the team is not treating the API as a product with its own maintenance requirements, but as an incidental byproduct of feature development.
THE QUESTIONS TO ASK IF YOU CANNOT REVIEW THE CODE YOURSELF
If you are a founder without the technical background to evaluate an API directly, these questions, asked of your technical lead or a technical advisor reviewing the system, will surface most of what matters.
If we needed to add a second consumer of this API tomorrow, a partner integration or a new client application, how much work would that be? A confident, specific answer suggests a well-designed API. A vague or concerned answer suggests significant hidden complexity.
How are errors handled across the API? Ask for an example of an error response and whether it looks the same across different endpoints. Inconsistency here is a reliable warning sign.
If we needed to change how a specific piece of data is structured, how many places in the codebase would need to change? A well-designed API isolates this kind of change. A poorly designed one spreads it across the system.
Is there a versioning strategy for this API? If the answer is no and there are already multiple consumers, that is a risk worth understanding before building further on top of it.
How is access control handled, and where does that logic live? A single, centralised answer is reassuring. A description of checks scattered across different parts of the code is a signal worth taking seriously.
None of these questions require you to understand the technical answer in full detail. What you are listening for is confidence and specificity. A technical lead who has thought carefully about API design will answer these questions quickly and precisely. A technical lead who has not will hesitate, generalise, or need to go check the code before answering, which is itself useful information about how well understood the system currently is.
WHAT TO DO IF THE ANSWERS ARE CONCERNING
Discovering that an API has significant design debt is not, by itself, a reason to panic or to rebuild immediately. The same framework that applies to broader technical debt applies here: is the problem structural or incidental, how concentrated is it, and what does the cost of addressing it compare to the cost of continuing to build on top of it as it is.
An API with inconsistent error handling but a sound underlying resource model is a targeted fix. An API with no separation between authorisation logic and business logic, spread across every endpoint inconsistently, is a more structural problem that may justify a more significant redesign of that specific layer, even if the rest of the system does not need to change.
The value of running this evaluation early, before committing significant further product development on top of the API, is that it gives you the choice of addressing these issues while the cost is still low. An API with three consumers is meaningfully cheaper to fix than the same API with fifteen consumers, each of which now has to be coordinated through any breaking change.
CLOSING THOUGHT
An API that works today is not the same thing as an API that was designed well. The gap between those two things is invisible until the system is under enough pressure to reveal it, and by then the cost of addressing it has usually multiplied. Evaluating API design early, whether through direct technical review or through the right questions to the people who built it, is one of the highest-leverage things a technical founder can do before committing further investment to a system that may not be built to support where the product is going.
If you have an API you inherited or built early and want an honest assessment of whether it is a foundation worth building on, that is exactly the kind of review I can help with. Tell me about your system and what you are trying to build next.