Building APIs That Survive Five Years of Customer Change Requests

What you actually need to know

• Design the API for the typical case, not the first customer.
• Additive changes only after launch. Breaking changes are expensive.
• Cursor based pagination for any growing list.
• Consistent error structure across all endpoints.
• Major versions in the URL. Minor changes are additive.

The core argument

An API that lasts five years is the product of a thousand small disciplines. Each one is unglamorous. The combined effect is an API that customers integrate once and keep using. The teams that skip the disciplines ship APIs that customers complain about for the entire relationship.

The discipline starts at design time. The schema is picked deliberately. The naming is consistent. The endpoints serve the typical case, not the first customer's specific case. The pagination is cursor based from day one because adding it later requires a migration. The error structure is uniform. The versioning is planned.

The discipline continues after launch. Every change is examined for additive versus breaking. The team chooses additive whenever possible. Breaking changes are announced months in advance with migration tooling. The team accepts the cost of additive changes to keep the API stable for customers.

The cost of getting this wrong is hidden until it lands. The first time you have to make a breaking change with no migration plan, every customer integration breaks. The support load spikes. Some customers leave. The lesson lands. The next API the team builds is much better. The trick is to skip the lesson and build the second API the first time.

Design choices that compound

The choices look small. They compound across every endpoint and every customer integration.

How much does this cost

The design discipline costs roughly one to two extra weeks at the start of the API project compared to the lazy version. The savings over five years are dramatic. Customer support load that does not exist. Breaking change migrations that do not happen. Engineer time not spent retrofitting consistency. The math is favorable from week one.

The ongoing cost is the review discipline. Every API change is examined for additive versus breaking. Every change to a public endpoint requires documentation update. The cost is real but small for a team that has built the habit.

Features the API must have

• A schema document that is the source of truth.
• A versioning strategy that is documented and respected.
• Deprecation headers and a deprecation policy.
• A changelog that customers can read.
• A consistent error structure.
• A request ID on every response.
• Rate limit headers on every response.
• A clear contract for backward compatibility.

Expert opinion

The APIs that last are the ones that were designed for longevity. The team accepted the constraints early. The naming is consistent. The shapes are stable. The errors are uniform. The decisions that look pedantic in week one are the decisions that pay off in year five. The teams that skip the discipline build APIs that customers tolerate, not APIs that customers integrate enthusiastically.

>

Yashveer Singh, founder of Yashveer Labs

How this played out on a real project

A client SaaS had built a public API in their first year with no design discipline. Different endpoints used different field naming conventions. Pagination was offset based. Errors had three different shapes depending on which engineer wrote the endpoint. Customers had to write per endpoint adapters.

We did not break the existing API. We added a v2 namespace that followed strict design rules. New customers used v2. Existing customers were given a year to migrate with full tooling support. The migration finished cleanly.

Three years later the v2 API has had no breaking changes. New endpoints are added monthly. The shape stays consistent. The customer integration cost is dramatically lower than the v1 version. The team has not had to retrofit consistency because it was there from the start of v2.

For more on the related work, see the API versioning strategy that survives real world use and designing an API that customers will not curse in five years.

Common mistakes teams make

1. Designing for the first customer's specific use case.
2. Inconsistent field naming. Customers write adapters.
3. Offset based pagination on growing lists.
4. Different error structures on different endpoints.
5. Breaking changes without a migration plan.
6. Missing changelog. Customers cannot tell what changed.
7. No deprecation headers. The deprecation is invisible.
8. No request ID. Debugging is a fishing expedition.

A 30 day API design checklist

1. Week one. Pick the conventions. Naming, IDs, timestamps, money, enums.
2. Week two. Design the error structure. Pick the pagination strategy.
3. Week three. Draft the schema. Have it reviewed by a senior engineer.
4. Week four. Write the documentation. Build the changelog.

For more on the related work, read REST vs GraphQL vs gRPC a decision matrix for founders and pagination patterns cursor vs offset and why it matters. On the broader documentation side, API documentation that developers actually read is the natural next read.