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.
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 it once, and that integration runs for years. Every breaking change costs them engineering time. Every inconsistency costs them cognitive load. The API that customers love at year five is the one 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
One SaaS client had rushed their first public API to land a single specific customer. The API used inconsistent naming, offset based pagination, and three different error formats depending on which engineer had written 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.
FAQ
Frequently asked
- What is the single most important API design rule?
- How do I avoid breaking changes?
- What about pagination?
- How do I handle errors?
- What about authentication?
- How do I version?
- What is the most common design mistake?
Author
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.