The API Contract I Didn't Know I Needed

Deborah Fabusuyi — Tue, 29 Sep 2026 08:35:00 +0000

One thing I've learned while working on production applications is that writing the frontend code is often not the hardest part.

Sometimes, the harder problem is understanding exactly what you're building.

Recently, I was working on a feature that depended on a backend endpoint. My initial approach was straightforward: inspect what was available, make a few assumptions about the response, start building the UI, and resolve the gaps as they came up.

It worked.

But it also created unnecessary back-and-forth.

During an engineering conversation, I came across the idea of an API contract and realised it described exactly what was missing from my approach.

An API contract creates a shared understanding between the frontend and backend about how they communicate:

What data is sent
What data is returned
The structure and types of that data
Required and optional fields
Possible states and status values
How errors and edge cases are handled

Instead of building around assumptions, both sides have an agreed interface to build against.

That immediately made me think about the feature I was working on.

So I sat down with the backend developer and we walked through the endpoint together.

We clarified what each field represented, what the response would look like, which states we needed to account for, and what should happen when certain data wasn't available.

The impact was simple but significant: the ambiguity disappeared.

The backend developer could focus on the endpoint and business logic. I could focus on consuming the response and designing the UI around the states we had agreed on.

More importantly, we could work in parallel without constantly making assumptions about each other's work.

The mental model changed for me

I used to think about API integration roughly as:

Backend builds → frontend consumes → UI gets built

I'm starting to see it more as:

Frontend + Backend → agree on the interface → build independently → integrate

That middle step doesn't need to be a formal ceremony.

Sometimes it's just asking:

"What exactly does this field mean?"

"What values can this status have?"

"What happens when this data isn't available?"

Those questions can prevent hours of unnecessary implementation and rework.

My takeaway

I'm learning that becoming a stronger frontend engineer isn't only about getting better at React, TypeScript, or the tools we use to build interfaces.

It's also about understanding the systems around the interface.

That means communicating clearly with backend engineers, identifying ambiguity early, thinking through edge cases, and creating enough shared understanding for different parts of a team to move independently.

Sometimes the thing blocking you isn't a difficult technical problem.

It's an undefined assumption.

And sometimes the best next step after receiving a ticket isn't opening your editor.

It's talking to the person building the other side of the system.

The Bug That Only Existed Between Two Systems

Deborah Fabusuyi — Thu, 03 Sep 2026 11:55:08 +0000

The Setup

I was working on a system with two separate dashboards: one used internally by a review team, and one used by external users. They're built and maintained somewhat separately, but they share data.

A flow I worked on recently tied them together: when the review team needs someone to resubmit something, they leave a comment explaining why. That comment is supposed to travel all the way to the external dashboard, show up as the reason for the request, and then travel back automatically once the resubmission happens, so the review side sees their own original comment again against the new submission.

QA flagged that sometimes the comment just wasn't showing up.

Tracing the Loop

This wasn't a bug I could find by staring at one component. The comment is meant to flow from the review side, through a notification the external dashboard picks up, back out automatically on resubmission, and land again on the review side against the new submission, a round trip across two separate apps, not a single feature.

To find where it broke, I had to actually follow data across both apps rather than trust that "my component looks correct." That meant reading through a part of the codebase I didn't normally touch.

The Actual Bug

The relevant piece of code handled two kinds of submissions differently — one path for file uploads, one for text-based responses. And they'd each gone wrong in a different way:

The file upload path just... didn't include the comment field at all when building the payload. It wasn't broken, it was omitted.
The text path included a comment, but a hardcoded placeholder string, not the actual comment that had come in from the notification.

Neither path was doing the one thing that mattered: pass through the real comment value it had already received, and only when one actually existed.

The Fix

The fix itself was small once the actual cause was clear:

Read the real comment from the incoming data in both paths.
Only include it in the payload when it's actually present — omit the field entirely rather than sending an empty string when there's nothing to say.

That last part mattered more than it sounds. Sending an empty string where the field should be absent is a subtly different contract, and downstream code that checks for the field's presence (rather than its truthiness) would have handled it wrong.

To illustrate the shape of the fix (not the real code, just the pattern):

// Before: comment field always present, sometimes with a placeholder
const payload = {
  ...otherFields,
  comment: comment || 'N/A',
};

// After: comment field only present when there's something real to say
const payload = {
  ...otherFields,
  ...(comment ? { comment } : {}),
};

The difference looks small, but payload.comment === undefined (field absent) and payload.comment === '' (field present but empty) are not the same thing to a consumer checking 'comment' in payload.

What This Reinforced

This bug couldn't have been caught by looking at either side in isolation — one side's code was fine, and the other side's file-path failure only mattered in combination with what the first side expected back. It only became visible once I treated it as one data flow spanning two codebases, not two separate features that happened to be adjacent.

The other small thing worth remembering: "the field is missing" and "the field is empty" are not the same bug, and conflating them means you can fix one and leave the other standing. Being precise about that distinction — omit vs. empty — was what actually closed the loop.

DEV Community: Deborah Fabusuyi