The API Spec Is Where Your Teams Finally Meet
I've seen it too many times. Backend builds an endpoint, frontend integrates against it, and somewhere along the way things don't match up. A field that's suddenly null. A status code nobody discussed. An enum value that doesn't exist on the other side. The classic back-and-forth starts: Slack messages, "can you check your endpoint?", hotfixes, frustration.
And honestly, most of the time the root cause is the same: both teams had a different picture of what the API looks like.
Just Talk About the Spec
Here's what helped me: stop talking about code and start talking about the spec. Not Java, not TypeScript. Just a plain OpenAPI file that describes what the API does. Endpoints, fields, types, what's required, what's not.
When you sit down together and write that spec, or even just review it as a team, the conversation changes. It goes from "what does your endpoint return?" to "what should this contract look like?" Backend brings what's feasible, frontend brings what's needed, and you meet somewhere in the middle.
That YAML file isn't just documentation. It's your agreement.
Both Sides Generate From It
Once you have the spec, both teams can generate their code from it. The backend gets server interfaces to implement. The frontend gets a typed client. Nobody writes fetch wrappers by hand, nobody guesses at response shapes.
And here's the thing: both sides have to fulfill the same contract. If the spec says a field is required, the backend has to deliver it and the frontend can count on it. No more "well, it's sometimes null." It's written down.
Compare that to what most teams do today: the backend generates a spec from code. Which sounds convenient, until you realize that the output looks different depending on whether you're using Spring Boot, FastAPI, or .NET. Each framework has its own quirks, its own gaps. Half the time you end up adding annotations just to make the generated spec match what you actually meant. At that point you're maintaining the spec anyway, just through a worse interface.
The Tooling Is Already There
This isn't some theoretical idea. Tools like OpenAPI Generator and openapi-ts have been around for a while and they work well.
What I really like: you can keep your spec in its own Git repo and hook up a pipeline that generates packages in whatever language you need. TypeScript client, Java interfaces, Python SDK, whatever your teams use. Someone updates the spec, the pipeline runs, and both teams pull the latest package as a regular dependency. No copy-pasting, no manual syncing.
You're already doing the design work somewhere. Might as well put it in a place where tooling can actually pick it up.
It's About Working Together
Look, I'm not saying this solves all your problems. But in my experience, the moment teams start owning the spec together instead of tossing it over the wall, things get noticeably smoother. Fewer integration surprises, fewer "I thought you meant..." conversations, less wasted time.
The API doesn't have to be a wall between frontend and backend. It can be the thing that connects them.
Happy to discuss. Find me on X @igoriuz.