Designing an API That Customers Will Not Curse In Five Years
An API that customers will not curse in five years is the result of decisions made at week one. Stable shapes. Additive evolution. Consistent naming. Clear errors. Cursor based pagination. Versioning that respects existing integrations. The discipline is unglamorous. The result is an API that customers integrate once and keep using rather than tolerating.
Written by Yashveer Singh, founder of Yashveer Labs.
What you actually need to know
- Consistency across endpoints is the single most important rule.
- Additive evolution only after launch.
- Cursor based pagination for growing lists.
- Consistent error structure across all endpoints.
- Versioning that respects existing integrations.
| Decision | Right pattern |
|---|---|
| Naming | Consistent. snake_case or camelCase. Same across endpoints. |
| Pagination | Cursor based on growing lists |
| Errors | Consistent shape with type, message, request ID |
| Authentication | API keys plus OAuth, picked deliberately |
| Versioning | Major in URL, additive minor |
| IDs | Opaque strings, type prefixed |
| Timestamps | ISO 8601 UTC with Z suffix |
| Money | Integer minor units, never floats |
The core argument
An API is a contract that lives much longer than any individual feature. The customer integrates the API once. The integration runs for years. Every breaking change costs the customer engineering time. Every inconsistency costs the customer cognitive load. The API that customers love at year five is the API that respected the contract from year one.
The discipline is small at week one and accumulates value across years. Consistent field naming. Stable shapes. Additive evolution. Cursor based pagination from day one because adding it later requires a migration. Consistent error structure. Clear versioning. Each decision is a small one at week one. The combined effect is an API that customers integrate enthusiastically.
The mistakes are equally consistent. Designing the API for the first customer's specific use case. Inconsistent naming across endpoints. Offset based pagination on growing lists. Different error formats per endpoint. No versioning strategy. Each is small in isolation. The combined effect is an API that customers tolerate while they look for an alternative.
The teams that get this right invest two extra weeks at the start of the API project. Schema review with a senior engineer. Naming convention documented. Error format committed. Pagination strategy picked. Versioning policy documented. The two weeks compound across years of customer integrations.
The design choices that age well
| Choice | Pattern |
|---|---|
| URL design | RESTful with plural nouns, kebab case |
| Field naming | snake_case or camelCase, picked once |
| IDs | Opaque strings with type prefix |
| Timestamps | ISO 8601 UTC ending in Z |
| Money | Integer cents, decimal currency separate |
| Nullable | Explicit null, not missing |
| Enums | Stable string values |
| Pagination | Cursor based on growing lists |
| Filtering | Query parameters with documented operators |
| Sorting | Single field, ascending default |
| Response envelope | Consistent. data, meta, errors. |
| Errors | type, message, request_id |
| Rate limits | Headers on every response |
| Idempotency | Idempotency-Key header on writes |
How much does this cost
| Investment | Cost |
|---|---|
| Initial design review | One to two weeks |
| Documentation of conventions | Days |
| CI checks for consistency | Days |
| Schema reviews ongoing | Hours per change |
| Versioning infrastructure | Days |
| Deprecation framework | One sprint |
Features the API must have
- A documented schema as the source of truth.
- A versioning strategy.
- A deprecation framework with timeline.
- A changelog customers can read.
- Consistent error structure.
- Request ID on every response.
- Rate limit headers on every response.
- Idempotency support on write endpoints.
- Backward compatibility commitment.
Expert opinion
The APIs that customers love five years after launch are the APIs that were designed for longevity from week one. The decisions are not exotic. Consistency. Stability. Additive evolution. Clear errors. The team that respects these from the start ships an API that compounds in value. The team that does not produces an API that customers complain about for the entire relationship.
>
Yashveer Singh, founder of Yashveer Labs
How this played out on a real project
A client SaaS had built their first public API quickly to land one specific customer. The API used inconsistent naming, offset based pagination, and three different error formats depending on which engineer wrote the endpoint. Customer integrations were painful.
We did not break the v1 API. We launched a v2 with strict design discipline. Consistent naming. Cursor based pagination. Single error format. Stable contract. Customers migrated over a year with full tooling support.
Three years later the v2 API has had zero breaking changes. New endpoints get added monthly with the same discipline. The customer integration cost is dramatically lower than v1. The customer satisfaction with the API has been the highest of any product surface.
For more on the related work, see building APIs that survive five years of customer change requests and the API versioning strategy that survives real world use.
Common mistakes teams make
- Designing for the first customer's use case.
- Inconsistent naming across endpoints.
- Offset based pagination on growing lists.
- Different error formats per endpoint.
- No versioning strategy.
- No changelog.
- No deprecation framework.
- Treating the API as solved once shipped.
A two week design exercise
- Days one to three. Pick conventions. Naming, IDs, timestamps, money, enums.
- Days four to six. Pick error structure. Pick pagination strategy.
- Days seven to nine. Draft schema for the first endpoints. Review with a senior engineer.
- Days ten to fourteen. Document conventions. Set up CI checks. Start the changelog.
For more on the related work, read building APIs that survive five years of customer change requests and pagination patterns cursor vs offset and why it matters. On the broader API side, API documentation that developers actually read is the natural next read.
Frequently asked
The engineering bet behind Yashveer Labs
The bet I am running with Yashveer Labs is simple. Most software is built by people who treat it as a job. I treat it as a craft. Yashveer Singh, founder. Five production systems on the board so far. The arc points at machine learning, AI engineering, and cybersecurity. If your project is in any of those orbits, you are reading the right page.
Posts that line up with this one.
- Backend, APIs, and System Design
Building APIs That Survive Five Years of Customer Change Requests
An API that survives five years was designed to. The ones that did not survive were designed for the first customer. Here is the discipline that keeps the API stable while the product evolves underneath it.
- Backend, APIs, and System Design
Idempotency Keys: A Pattern Every Senior Engineer Should Master
Idempotency keys are a small implementation with an outsized impact on system reliability. Here is the pattern, the edge cases, and the production pitfalls that most introductions skip.
- Backend, APIs, and System Design
JSON Columns in Postgres: When They Make Sense
JSON columns in Postgres are genuinely useful for flexible, semi-structured data. They are also frequently misused as a shortcut to avoid schema design. Here is when to use them and when to use normalized tables instead.
- Backend, APIs, and System Design
Kafka in 2026: When You Need It and When You Do Not
Kafka is powerful, but most startups reach for it before they need it. Here is how to decide.