Latest / The API Podcast with Fexingo: REST, GraphQL, and Modern Web APIs / How API Schema Evolution Prevents Breakage
Transcript
- Lucas: Let’s talk about the most dangerous moment in an API’s lifecycle. It isn’t when you launch it. It’s the day after you decide to change it. Most engineers think of APIs as static contracts. But in reality, every successful API is a living organism that has to evolve or die. The problem is that evolution usually breaks things. Luna: Right, because your downstream consumers are running on their own schedules. You push a patch on Tuesday, and their QA cycle doesn’t start until next month. By then, it’s already too late to fix the integration without a rollback. Lucas: Exactly. And the worst part is that most breakage is self-inflicted. We tend to treat schema changes like database migrations. In databases, you can add a column without touching the old code. But in REST or GraphQL, if you rename a field or remove a nested object, you don’t just get a warning. You get a five-hundred error. That’s not a bug. That’s a broken business relationship. Luna: So the real challenge isn’t technical complexity. It’s coordination. How do you align the timeline of your internal product roadmap with the external stability promises you made to developers three years ago? Lucas: It’s coordination plus discipline. I want to look at a specific pattern here: the concept of soft deprecation. A few years ago, a major payment gateway had to retire a legacy currency format. They didn’t just flip a switch. They introduced a new field called 'currency_iso_code' alongside the old 'currency_code'. For eighteen months, both fields existed. The old one was marked deprecated in the documentation, but it never actually stopped returning data. Luna: That’s interesting. So they were essentially paying a performance tax for eighteen months to allow everyone to migrate at their own pace? Lucas: Precisely. And here is the key detail that most teams miss. They didn’t just leave the old field there. They started sending a specific HTTP header on every response containing the old data. Something like 'X-Deprecated-Field: currency_code'. This allowed client-side libraries to log warnings automatically. Developers saw the issue in their console logs before their apps even crashed. Luna: That turns a silent failure into a visible alert. Instead of your customer calling support because payments failed, your developer sees a yellow warning in their dashboard and fixes it during a scheduled sprint. That shifts the burden from reactive firefighting to proactive maintenance. Lucas: Yes, and it creates a feedback loop. Once eighteen months passed, they removed the old field entirely. Because the header logging had done its job, less than two percent of active integrations broke. The rest had migrated voluntarily. If they had just killed the field on day one, that percentage would have been closer to forty percent. That’s revenue loss. That’s churn. Luna: But what about the clients who didn’t read the docs? Or the ones using automated scrapers that ignore headers? Doesn’t that still leave a gap? Lucas: It does. Which is why we need to talk about contract testing. But not the kind where you just mock the endpoint. I’m talking about consumer-driven contract testing. This is where the client defines what it expects, and the server proves it delivers. It’s not enough to say the API works. You have to prove the specific consumer works. Luna: So you’re validating the handshake, not just the signal. If my client expects a string and you send a number, the test fails before deployment. That prevents the runtime error. Lucas: Correct. And this brings us to a nuanced point about GraphQL versus REST. In GraphQL, you can technically add a new field to a query without breaking anything. It’s additive by nature. But if you remove a field that someone is actively querying, you break them. The temptation in GraphQL is to be aggressive with schema cleanup. But that aggression is exactly what causes integration chaos. Luna: I’ve seen teams try to clean up their GraphQL schemas by removing unused types. They spend weeks refactoring internally, only to realize that some partner app was relying on a 'ghost' field that hadn’t been updated in two years. It worked because it was null-safe, so nobody noticed. Then they deleted it, and the partner app broke. Lucas: That is a classic graveyard scenario. The lesson is that 'unused' in your codebase does not mean 'unused' in the wild. Your internal usage metrics are lying to you. The only truth is the actual traffic hitting the edge. And even then, traffic metrics are lagging indicators. By the time you see zero requests to a field over thirty days, you might still have one critical enterprise client waiting for a monthly batch export. Luna: So the metric isn’t volume. The metric is diversity of consumers. One high-value consumer matters more than ten thousand anonymous bots. How do you track that without building a massive analytics infrastructure? Lucas: You don’t need massive infrastructure. You need good logging. Tag every request with the client identifier. Group by that identifier. When you plan a schema change, cross-reference your list of active client IDs against your planned deletions. If any top-tier client is still using a field slated for removal, you pause. You reach out. You extend the deadline. It’s basic account management, applied to code. Luna: That sounds simple, but it requires a level of humility that engineering teams often lack. We want to ship clean code. We want to remove the clutter. But shipping clean code shouldn’t come at the cost of breaking the people who pay for the service. Lucas: Exactly. Clean code is an internal virtue. Stable APIs are an external obligation. There is tension there, and you have to manage it consciously. Now, let’s pivot to a slightly different angle. What happens when you need to change the of data, not just the names? Like moving from a flat list to a nested object. Luna: That’s a nightmare. Because you can’t just add a field. You have to replace a field. If you have an address that was previously a single string '123 Main St', and now you need 'street', 'city', 'zip', you can’t fit all that into one string without parsing it on the client side. That’s a breaking change. Lucas: Right. So the pattern here is the 'wrapper' object. You introduce a new field called 'address_details' which is an object. But you keep the old 'address_string' field alive for another year. You populate the new object with parsed data from the old string. Clients can start reading 'address_details.city'. Old clients continue reading 'address_string'. Eventually, you stop populating 'address_string'. You don’t delete it immediately. You just stop filling it. Then, after a grace period, you delete it. Luna: That’s clever. You’re essentially providing a translation layer at the API boundary. You’re doing the heavy lifting of migration for the consumer instead of forcing them to write a parser. That reduces friction significantly. Lucas: It reduces friction, but it increases your server load. You are now parsing and serializing data on every request for a year. That’s a cost. But remember, we talked earlier about caching. If you cache the response, this parsing happens once per cache key, not per request. So the marginal cost drops to near zero. It’s a trade-off: compute power for developer happiness. Luna: And developer happiness translates to adoption. If your API is easy to use, people build more features on top of it. More features means more stickiness. It’s a long-game investment. But it requires upfront planning. You can’t decide to do this six months after the bad data starts causing issues. You have to anticipate the structure change before it becomes urgent. Lucas: Anticipation is the hard part. Most teams react to problems. They see a spike in support tickets about malformed addresses, and then they scramble to fix it. A mature API team looks at their data quality metrics quarterly and says, 'Hey, twenty percent of our address fields are incomplete. Let’s design a migration path now, before it breaks production.' It’s proactive governance. Luna: It feels like treating the API like a product, rather than a utility. When you treat it as a utility, you just turn the tap on and off. When you treat it as a product, you care about the user journey, the onboarding, the upgrades. It’s a mindset shift from engineering to product management. Lucas: Spot on. And that’s where the donation segment fits in naturally. If today's tech conversation gave you something usable... Lucas: about keeping your integrations stable and your customers happy, you might appreciate supporting the work that keeps these deep dives coming. Listener support is what keeps Fexingo Business ad-free and independent. If you find value in these episodes, consider buying me a coffee at buy me a coffee dot com slash fexingo. It helps cover the servers and lets us dig deeper into topics like this. Luna: Yeah, it really makes a difference. Knowing that listeners are behind the research allows us to spend time on cases like this payment gateway example, rather than just skimming the surface. Lucas: Thanks for the support. Now, back to the structural changes. There’s one more pattern I want to touch on, and it’s controversial. Versioning in the URL versus versioning in the header. You know the debate. Do you go '/v1/users' or '/v2/users'? Or do you keep '/users' and put the version in the Accept header? Luna: The URL versioning is easier to debug. You can see the version in the browser history. But it clutters the route table. The header versioning is cleaner, but it’s harder for mobile clients to cache correctly. Different caches behave differently based on headers. Lucas: Here is the pragmatic view. If you are following the soft deprecation model we discussed, you don’t need strict URL versioning. Because you are maintaining backward compatibility within the same endpoint. The URL stays '/users'. The schema evolves slowly. You only need a new URL version if you are making a fundamental architectural shift that cannot be supported by additive changes. Like moving from synchronous REST to asynchronous event streams. Luna: So versioning should be rare. It should be reserved for big leaps, not small tweaks. That aligns with the idea that stability is the default state. Change is the exception, and it must be handled carefully. Lucas: Exactly. If you are versioning every minor release, you are admitting that your schema design is too rigid. You are failing to provide the flexibility that modern APIs should offer. Good API design anticipates change. It builds room for growth. Bad API design forces a fork every time you need a new feature. Luna: That’s a high bar. It requires deep understanding of the domain. You have to know what fields might change in the future. You have to design for elasticity. It’s harder to do upfront, but infinitely easier than managing fifty versions of your API five years down the line. Lucas: Absolutely. And that’s the core message here. Schema evolution isn’t a technical afterthought. It’s a strategic imperative. The companies that master it will have fewer support tickets, happier developers, and more resilient ecosystems. The ones that don’t will spend half their engineering budget just trying to keep the lights on. Luna: It’s interesting to think about how this applies beyond just web APIs. Data pipelines, internal microservices, even third-party integrations. The principles of soft deprecation and additive change are universal. Stability is the ultimate feature. Lucas: It is. And as we move further into 2026, with AI agents starting to consume APIs directly, the stakes are higher. An AI agent won’t gracefully handle a missing field. It will just fail. So our standards for robustness need to go up, not down. We need to build APIs that are resilient not just to human error, but to machine interpretation. Luna: That’s a forward-looking question. If AI agents are the new consumers, does that change how we document our schemas? Do we need machine-readable descriptions to be perfect, because there’s no human to interpret the ambiguity? Lucas: That is the next frontier. And it’s why open specifications like OpenAPI and AsyncAPI are becoming so critical. They aren’t just documentation anymore. They are executable contracts for intelligent systems. The way we write those specs today will determine how easily our APIs survive the next decade of technological change.