Stop Guessing Your API: Contract-First React with OpenAPI

Quick question. How many of you have had a front-end bug that turned out to be a backend field renamed that nobody told you about? Yeah, that's what this talk is about fixing. I'm Violina, and for the next minutes, I want to show you how we at Click My Horse TV stopped guessing our API and what happened to our team, our apps, and even our AI workforce when we did. Let's get into it.

We built a system that worked. React on web, React Native on mobile, a backend, real users. By most measures, it was fine. And then, slowly, it wasn't. Not because something broke, because nothing was ever quite aligned. And over time, that misalignment compounded into something we couldn't ignore. This is the story of what we found, what we did about it, and what it unlocked, including some things we didn't expect.

Here is the setup. React web frontend, talking to a web API. React Native, talking to a mobile API. Two teams, two backends, one product. Everyone has clear ownership. No shared state to step on each other. Independent release cycles. We drew this on whiteboard in the early days, and it made sense. I remember thinking, this is clean. This is how you scale a team. On paper, this looked perfectly reasonable. The problem with systems like this is that the whiteboard never shows you what happens three years later. Two teams, same product domain. APIs evolving independently. That combination is where it starts. Every engineer makes reasonable local decisions. You name a field what makes sense to you. You structure a response the way your data model suggests. You mark something optional, because it might not always be there.

None of those decisions are wrong in isolation. But over years, each team's reasonable decisions add up to two systems that no longer speak the same language. Nobody planned it. Nobody noticed it happening. It just accumulated.

Years in, we started finding things like this. Web API, title, items. Mobile API, header, components. Same feature, same data underneath, but two completely different shapes coming out of two different endpoints.

And here's the thing. Neither side was wrong. Both work perfectly for their own platform. But the moment you needed to share logic or cross-reference behavior, or onboard someone new across both, you hit the gap.

Every time, it was a surprise. Every time, it cost time. And every time, we patched it and moved on because we didn't yet understand what we were actually looking at.

We were looking at Drift, same domain, different shapes. The costs don't show up in your error logs. They show up in your calendar. A runtime mismatch that took three days to trace because it wasn't a crash.

It was just wrong data rendered silently on the screen. Duplicate TypeScript interfaces across projects, slowly diverging in ways nobody tracked. Every cross-platform feature requiring a coordination meeting before anyone wrote a line of code.

A new engineer spending their first two weeks just trying to understand why the same concept had a different name in every place they looked. None of it felt catastrophic. It just felt slow. Velocity slowed down not because of complexity, but because of misalignment.

The clearest example of that misalignment is our entire mobile app. The API didn't just return data. It returned UI decisions. And none of this was malicious. It evolved that way because there was no shared agreement about what an API's job actually is.

In the absence of a contract, the API becomes whatever the client asks for in the moment. And then it stays that way forever. Every screen was an array of component descriptors the backend returned. Type header with left, middle, right slots. Type linear player. Type navigation card list.

The backend needed what to render, decided what to render, in what order, in what arrangement. The frontend was a rendering engine, nothing more. Once you have a pattern like that across an entire app, the consequences are predictable. Tight coupling. Frontend and backend locked into a structural dependency, neither team can change independently.

Nearly impossible to test. How do you unit test a component whose layout is determined at runtime by a remote service? Refactoring paralysis. And the team dynamic where every product question eventually becomes a backend question. It was clear that this wasn't a mobile problem. This was a contract problem. So we did what engineers do when something isn't working. We look for what we had.

Postman collections, two major versions behind reality, an internal client event catalog that someone had started with good intentions and quietly abandoned. Engineers who genuinely knew how things worked. Some of them had already left. We didn't have a shared source of truth. Sit with that for a second. The drift, the backend-driven UI, the three day debugging sessions. None of those were separate problems. They were all the same problem.

Because when the truth lives in people's heads, it lives when they do. Our first instinct is that, and I suspect it's a familiar one, was to write better types. If the problem is that frontend doesn't know what the API returns, we'll just write better TypeScript interfaces, more complete, more carefully maintained, more disciplined. We tried it. It didn't hold. Handwritten types are only as accurate as the last time someone remembered to update them.

The moment backend changes something and frontend doesn't know the type is live, they compile, they pass CI, and then they quietly deliver wrong data to your users. So we tried documentation. Richer entries in our internal event catalog. Annotated postman collections, a Slack channel for API changes also didn't hold. Documentation is a description of what exists at the moment of writing. By the time you read it, it's already slightly wrong, and you can't enforce it. You can't compile against an event catalog entry. You can't write a test that fails when the documentation is out of date. What we actually needed was something machine-readable, something that didn't tell you what the API was, something that generated the code you had otherwise write by hand and broke the build when reality diverged from the spec.

We needed a contract that the tools could read, not just the humans. OpenAPI, not as the documentation, as the source. Most of you probably have encountered OpenAPI through Swagger. That interactive docs page your backend generates. You open it, find the endpoint you need, expand the response schema, maybe click try it out, it's useful. It's better than nothing. But that's documentation, and documentations as we just established the case.

Here's the mental shift that changed everything for us. OpenAPI isn't a documentation format. It's a contract format. There's a difference. When you write status string in your TypeScript interface, you are guessing. You are saying, I think this field exists. I think it's string. I think these are the possible values. But I'm not certain, and nothing will tell me if I'm wrong. When status is defined in an OpenAPI spec, as an enum, with three specific values, that's a specification.

Backend has to implement it. Frontend generates type from it. If the spec says active, maintenance, or closed, those are the only valid values, and your TypeScript knows it. Your IDE knows it, and your CI knows it. Documentation tells you what exists. A specification defines what must exist, and critically, it lets tooling enforce it. Here's where it gets practical. You write your practical. You write your OpenAPI YAML. You run one command. What comes out? TypeScript types. Exact, generated, never handwritten. A typed API client for web.

The same client for React Native from the same spec. Mock response shapes for your tests, type against the same contract your production code uses. The tools that do this. Hey API gives you types plus a full SDK client in one shot. Orville generates non-stack query hooks directly from the spec. OpenAPI TypeScript is the minimal option. Types only, no other opinions.

When the spec changes, you regenerate. TypeScript tells you immediately where things broke, in both code bases, before you commit, before you open a pull request, before anything reaches production. You stop writing API code. You generate it. Contract-first means the spec isn't something you write after the feature is built. It's how the feature starts. A ticket gets picked up before anyone writes a handler or a component, someone opens the spec file and defines the shape of the API.

That definition gets revealed by backend, by frontend, by whoever consumes it. It gets merged. Then implementation begins on both sides simultaneously against the same agreed contract. The contract isn't a by-product of development. It's the input to it. It no longer is someone's head or buried in our event catalog. It's in the repository, versioned, revealable, and enforced. In concrete terms, four things changed. First, the API was defined in OpenAPI before any implementation started. The spec was the source, not the output. Second, TypeScript clients were generated for both web and mobile from that single spec. Not written, not maintained, derived.

Every time the spec changed, we regenerated. The backend implemented against the same spec the frontend consumed. Both sides were working from the same document for the first time. Contract mismatches broke builds instead of production. A renamed field triggered a type error in CI. Frontend and backend shared the same contract before any application code was written.

You define live event in the spec with specific requirements and newable elements. The generator produces a precise TypeScript interface. Use the generated interface for typed queries on the consuming side. Changes in the spec reflect immediately in both code bases. The truth resides in the spec, making everything downstream a derived artifact.

The spec itself details the structure in YAML format. Each field is defined with its data type. The generator ensures exact TypeScript interfaces. TypeScript alerts on mismatches or newable fields. Updates in the spec trigger immediate errors in both frontend and backend code. The spec serves as the foundational truth for all subsequent development.

You try to render image URL directly and TypeScript reminds you it could be new. If someone on the backend renamed name to event name, regenerates the client and opens the peer, the TypeScript error shows up immediately in both code bases. That's the moment you've been debugging manually for years. Now it's automatic. The spec is where the truth lives. Everything downstream of it is just a derived artifact.

This is the spec itself. Live event in YAML. ID is an integer, name and country code are strings. E-stop event is a Boolean. Image URL and next competition start at are newable. Stream is an array, each item referencing the live event stream schema. This is the file that lives in your repository, goes into code review, and has a Git history. When the backend team needs to change this, they change it here first. The pull request is a spec change before it's a code change. Both sides see it, both sides agree before anyone implements. The frontend no longer mirrors the backend manually; it compiles against it.

Mirroring is fragile as it relies on people staying in sync, while compiling is enforced and relies on the type system. The resulting architecture has the schema at the top, with web, backend, and mobile all pointing at the same schema. Unification of the backend is achieved through schema alignment, not just unification itself. A unified backend without a schema can still drift. The schema is the load-bearing piece. Despite having two separate code bases for web and mobile, the schema enforces alignment, ensuring concrete understanding of changes and maintaining consistency.

Compiling is enforced. It relies on the type system. The resulting architecture, schema at the top, web, backend and mobile all pointing at the same schema. We also unified the backend, but the schema is what enforces alignment, not the unification. A unified backend without schema can still drift. The schema is the load-bearing piece.

To be concrete about what changed and what didn't, we still have two separate code bases, web and mobile. We didn't merge them. They stay independent, deployed independently, owned independently. What changed? They now consume the same generated types from the same spec. Username on web and username on mobile, gone. One definition in the spec, generated into both. Consistent field names, consistent shapes, consistent new ability.

And each frontend keeps full ownership of its presentation logic. The backend returns domain data. What to do with that data, how to lay it out, what to show, what to hide, that stays on the frontend side where it belongs. Do you remember the example from the beginning, the one where the API was returning layout instructions instead of data? Once we had the spec, we had something we didn't have before. A formal definition of what an endpoint is for.

Do you remember the example from the beginning, the one where the API was returning layout instructions instead of data? Once we had the spec, we had something we didn't have before. A formal definition of what an endpoint is for. And when we wrote the spec for that mobile screen, it was immediately obvious that the response shape was wrong. Not subtly wrong, obviously wrong. It encoded tap order, it encoded section visibility. That's not API data, that's UI logic.

We went back, refactored the endpoint over several sprints and the result was a screen that the frontend team owned completely. Backend returned the domain data. Frontend decided what to render, in what order, under what conditions. The screen became testable without mocking a backend. It became something product could A-B test without a deployment. The contract didn't just align the systems, it made right boundaries visible.

And once you can see a wrong boundary, you can fix it. That shift sounds simple, but it's the difference between a UI that can be tested independently deployed and iterated on by a product team, and a UI that requires a backend engineer in the room for every design conversation. The contract made that boundary explicit. You can't accidentally put layout logic in a data contract when the contract is reviewed by both teams. Once we had the schema, we started getting real value out of AI-assisted development.

Once we had the schema, we started getting real value out of AI-assisted development. And I don't mean AI wrote some boilerplate. I mean the output was accurate in a way that hadn't been before. Before the schema migration, we had experimented with AI tooling, asked it to generate hooks, scaffold components, write test cases. The code looked right, it was plausible, but it called endpoints that didn't exist. It invented field names, it handled error states that weren't real.

After the migration, we started feeding the open API spec as context. Here's the contract, generate the hook for this endpoint. The output changed, field names were correct, return types matched, error handling reflected what the API actually returned. The model didn't improve, the input did. AI became reliable because the system was constrained. That's not a prompt engineering lesson, that's a system design lesson.

If you want reliable AI output, give it a precise specification to work from. Concretely, here's what that unlocked. We could prompt the model with the spec for an endpoint and get back a type React hook that actually worked. Not one that looked like it worked, one that compiled, matched the real API, and handled the fields correctly. We could generate realistic test mocks from the spec, and because the mocks came from the same schema as the production types, they couldn't drift.

A mock response that doesn't match the real API shape is just a test that lies to you. Ours couldn't, the spec prevented it. We could scaffold components that already knew the shape of the data they had consumed. The model wasn't guessing at the API surface. It was reading it.

The spec wasn't just a contract between our systems. It became the context that made automation trustworthy. The structure made automation reliable. How do you actually get here? AdoptOpenAPI is easy to say and hard to start. We started with one rule, any new endpoint gets a spec. New work goes through the schema from day one. No migration cost, no disruption, just a different starting point for new things.

From there, we gradually brought high impact existing endpoints into the spec, one at a time. Write the spec, run the generator, replace the handwritten fetched code and the handwritten type, delete the old code, net reduction in code every time. Frontend and backend could now develop in parallel on the same feature. Integration streamlined from a week-long process to a more efficient workflow. Ownership of the spec file and approval processes were key discussions to ensure alignment between teams.

The old and new approaches coexisted without friction. There was no cutover, no freeze week, just a growing percentage of the codebase that the spec owned. And something else happened that we didn't fully anticipate. Frontend and backend could now develop in parallel on the same feature. Backend implementing against the spec, frontend building against generated mocks derived from the same spec. Both teams working from the same contract converging on the same endpoint shape. Integration went from a week-long process of discovering mismatches to disable the mocks, run the tests, ship it, start with one endpoint.

I'm not going to tell you this was free. The first real conversation we had was about ownership. Who owns the spec file? Who has to approve a change to it? If that's unclear, the spec becomes a point of conflict instead of a point of alignment. We resolved it by making the schema a shared artifact. Changes revealed by backend and frontend teams together. One approval process, two perspectives. Keeping the spec honest is ongoing work.

If a backend engineer ships a field change without updating the spec first, the spec lies. And the lying spec is worse than no spec. Because it gives you false confidence. We put CI checks in place. The spec is validated against the running API on every merge. That required tooling investment. It was worth it, but it wasn't free. Naming conventions, camel case or snake case seems trivial until you have two teams with different habits and a spec that has to pick one. We had the conversation once, made the call, wrote it into the spec, done. But we had to have it. And some backend engineers had never thought about their API as a contract before. That's not a criticism. It's just a different mental model. We spent time on it. All of that was real cost. None of it was a reason not to do it.

I want to be honest about where this pays off and where it might be overkill. It's worth the investment when you have multiple frontend clients consuming the same API. When the product is long-lived and the API will be versioned and maintained over years. When the team is growing and you can't rely on shared context anymore. When domain complexity is increasing and the gap between what the API does and what the frontend assumes it does is getting harder to breach. It's probably overkill for a single client prototype you control end-to-end. Or a project with a six-week lifespan where you're the only consumer.

The question to ask is how much does API drift cost us and is it getting worse? If the answer is yes, this is the right tool. So let's be precise about what actually moved the needle. Because it wasn't the tooling. The code generator is just a mechanism. Hey API, Orval, OpenAPI TypeScript, those are just programs. They do what you tell them. What reduced the depth was the decision that preceded all of them. A shared contract at the boundary. One place, one file, one source of truth for the shape of every API interaction across the system.

Explicit schema evolution, meaning no silent changes. Every field adoption, every rename, every duplication goes through the spec first. Gets revealed, gets versioned, nothing mutates without a record. Contract mismatches breaking builds instead of production. That category of bug, the one where a field changed and nobody told the frontend, just stopped happening. And the clear separation of concerns. Backend owns domain data. Frontend owns presentation. The spec is the line between them.

Tech depth accumulates when implicit agreements decay. Every undocumented convention, every assumption held in someone's head, everything that everybody knows, all of it is depth waiting to be called. The schema made our arrangements explicit, that's what stopped the decay.

Four things I would want you to take back from this. Treat the API as a product. It has consumers. It has a life cycle. It will outlive the sprint that created it. Give it the same design discipline you give your UI. Intentional, versioned, owned. Define the contract before implementation starts. Not as a documentation step after you are done. As the thing that makes implementation possible. It changes what starting a feature means for both teams.

Don't let your backend make UI decisions. If your API response and codes layout order of visibility, that's a contract problem waiting to become a refactoring problem. The spec makes those boundaries visible before they calcify. And use schemas to empower your tooling. All of it. Type generators, mock libraries, AI assistants. They all get better when the contract is precise and machine readable. The schema is the input that makes automation reliable. We started with two frontends, two backends and no shared agreement about anything. We ended with two frontends, one backend, one contract. Alignment replaced drift. Look at this diagram. React web and React native both pointing at the same open API spec. Both talking to the same backend. The arrows aren't just architecture. They are agreements.

They are the thing we didn't have for years. Finally written down. The contract is what lets you rename a field and know immediately what breaks. It's what lets a new engineer understand the system without calling anyone. It's what lets an AI assistant generate code that actually compiles. It's what lets the backend team ship a change without coordinating with both frontend teams first. The contract became the boundary of trust. Type safety isn't about types. It's about trust between systems. Thank you.