Why Most API Design Advice Misses the Point
After fifteen years of building APIs that have processed billions of requests, I’ve noticed something peculiar about most API design discussions. Everyone talks about REST versus GraphQL, argues about HTTP status codes, and obsesses over naming conventions. Meanwhile, the systems that actually survive production load and developer sanity checks share deeper architectural patterns that rarely make it into Medium tutorials.
The truth is, good API design isn’t about following RESTful principles religiously or achieving perfect semantic versioning. It’s about understanding the fundamental forces that act on your system over time: evolution pressure, integration complexity, and the inevitable entropy that creeps into any system touched by human hands. The APIs that thrive are built with these forces in mind, not against them.
Let me share four patterns I’ve seen work consistently across different domains, team sizes, and technical constraints. These aren’t trendy frameworks or clever abstractions. They’re boring, battle-tested approaches that make your API resilient to the chaos of real-world software development.
Pattern One: The Expansion-Only Schema
The most painful API migrations I’ve witnessed all shared a common origin story: someone changed a required field or removed a property that seemed “obviously unused.” The expansion-only pattern treats your API schema as append-only data structure. You can add new fields, introduce optional parameters, and extend enums, but you never remove or change existing contracts.
This might sound restrictive until you realize it solves the distributed versioning problem entirely. When your mobile app, three different microservices, and that Python script Bob wrote two years ago all depend on your API, coordinating breaking changes becomes a project management nightmare. With expansion-only schemas, backwards compatibility becomes automatic.
The implementation details matter here. Mark new fields as optional by default, even if your current business logic requires them. Use feature flags or separate validation layers to enforce constraints without baking them into your schema. When you absolutely must deprecate something, leave the field in place but stop using it internally. Your future self will thank you when the “quick migration” doesn’t turn into a six-month cross-team coordination effort.
I’ve seen teams resist this pattern because it feels wasteful to carry deprecated fields forever. But consider the alternative: breaking changes that require coordinated deployments across multiple teams, roll-back strategies, and the inevitable emergency patches when someone discovers a dependency you missed. The cost of a few extra bytes in your JSON response is negligible compared to the operational overhead of breaking changes.
Pattern Two: Command-Query Responsibility Segregation at the API Layer
Most APIs conflate two fundamentally different operations: reading data and changing state. This leads to the classic REST dilemma where a single resource endpoint tries to handle both queries and mutations, resulting in awkward compromises and confusing semantics. The solution is to embrace the distinction explicitly through API-level CQRS.
Structure your API with clear separation between query endpoints that return data and command endpoints that trigger state changes. Query endpoints should be stateless, cacheable, and safe to retry. They might look like traditional REST resources, but with the understanding that they’re read-only views. Command endpoints follow a different pattern entirely: they represent actions or intentions rather than resource manipulations.
Here’s where it gets interesting: command endpoints should return minimal data, typically just an operation ID or status indicator. If the client needs fresh data after a command, they issue a separate query. This feels redundant at first, but it solves several problems simultaneously. Commands can be processed asynchronously without blocking the response. Query responses can be cached aggressively. And the API naturally supports eventual consistency models where state changes take time to propagate.
The mental model shift is important. Instead of thinking “update user profile,” you think “submit profile change command” followed by “query current profile state.” This separation makes your API naturally more scalable because queries and commands can be optimized, cached, and even stored differently without affecting the contract.
Pattern Three: Contextual Response Shaping
The biggest source of API bloat comes from trying to serve every possible use case with a single endpoint. You end up with massive response objects where most clients only care about a subset of the data, or proliferating endpoint variations that differ only in their level of detail. Contextual response shaping solves this by making the API adapt to the client’s actual needs.
Different client contexts genuinely need different data shapes. A mobile app listing users needs basic display information. An admin dashboard needs full profiles with permissions and audit data. A data export needs everything including soft-deleted records. Rather than forcing all these use cases through the same endpoint or creating separate endpoints for each variation, let the client specify their context.
This can be implemented through field selection parameters, client-type headers, or context enumeration. The important thing is that the API understands why the request is being made, not just what data is being requested. A mobile app and a desktop admin panel might both request “user profiles,” but they’re solving different problems and should get appropriately shaped responses.
The implementation requires discipline around context definitions and response mapping, but the payoff is substantial. Network overhead drops because clients only receive relevant data. Cache effectiveness improves because responses are tailored to specific use cases. And new client types can be supported by defining their context requirements rather than building new endpoints.
Pattern Four: Progressive Disclosure Through Linked Resources
The classic n+1 query problem has API designers reaching for complex query languages or trying to anticipate every possible data requirement upfront. Both approaches create more problems than they solve. Progressive disclosure takes a different approach: start with minimal data and provide clear paths to additional detail when needed.
Design your primary endpoints to return lightweight representations with embedded links to related resources. Instead of trying to decide whether a user list should include full profile data or just names, return basic information with explicit URLs for accessing additional details. This shifts the burden of optimization from the API designer to the client developer, who actually knows what data they need.
The magic happens in the implementation of these linked resources. They should be designed for efficient batching, so clients can request multiple related resources in a single follow-up call. Use consistent URL patterns that allow for programmatic construction of batch requests. And make sure these detail endpoints support the same contextual shaping patterns discussed earlier.
This pattern scales naturally as your data model grows. New relationships can be exposed through additional links without changing existing response structures. Clients that need performance can implement intelligent prefetching strategies. And debugging becomes easier because you can trace exactly what data a client requested and why.
The Long Game of API Architecture
These patterns share a common philosophy: they optimize for change over time rather than current convenience. They assume your API will outlive the system it was originally built for, that requirements will shift in unpredictable ways, and that the cost of coordination across teams grows exponentially with system complexity.
The teams that get this right aren’t necessarily more skilled at predicting the future. They just build systems that bend without breaking when the future turns out differently than expected. Their APIs become platforms that enable rather than constrain the applications built on top of them.
What patterns have you found essential for API longevity? I’m always curious to hear about the boring, unglamorous techniques that actually keep systems running in production. The war stories are often more valuable than the architecture diagrams.