Catching Breaking API Changes Before Production (with a Chrome Extension)

Have you ever deployed code only to find out the backend changed an array to a string?

Your .map() breaks. Users complain.
You spend the next hour debugging something that was working yesterday.
This happened to me one too many times.

So I built API Inspector — a Chrome DevTools extension that tracks API schema changes while you’re developing, not after production breaks.

---

🎯 The Problem

Picture this scenario.

Week 1: Everything works

// API response
{
  "projectStatus": ["active", "pending"]
}

// Frontend usage
projectStatus.map(status => ...)

This is reasonable.
The API contract says projectStatus is an array.

Week 2: Silent backend change

The backend gets refactored. Now the API returns:

{
  "projectStatus": "active"
}

You deploy. Everything breaks.💥

---

“But why didn’t you add an array check?”

Yes — you could write:

Array.isArray(projectStatus) && projectStatus.map(...)

But that only hides the real problem.
The actual bug isn’t:

“.map() crashed”

The real bug is:

“The API contract changed and nobody noticed.”

Defensive checks treat the symptom.
They don’t surface breaking changes.
And that’s exactly what I wanted to catch.

---

💡 The Idea

I wanted something that would:

• Monitor API responses automatically
• Detect schema changes
• Show differences clearly (like a git diff)
• Work locally, without any third-party service

That’s how API Inspector was born.

---

🔍 What API Inspector Does

Once enabled in DevTools, it:

• Captures API requests (customizable by the user)
• Stores previous response schemas and compares them against new responses
• Highlights changes:
  • type changes (array → string)
  • added / removed fields
• Shows a diff view, similar to Git

Customization options

• Default filter: APIs containing "api/"

• Can be changed to:

  • any keyword
  • all JSON-based APIs

• No backend. No external storage.

• Everything runs locally in the browser.

---

🧩 Chrome Extension Architecture (At a High Level)

Before building this, I thought Chrome extensions were simple and made of just a few parts:

• Popup → UI only. Exists only while open. Used for controls and settings.

• Background Script / Service Worker → Runs separately from the page. Handles storage, listeners, and long-running logic.

• Content Scripts → Run inside the web page. Can read the DOM, intercept requests, but have limited access.

• DevTools Panel → A completely separate execution context tied to Chrome DevTools — not the page, not the background.

In practice, this is where things got tricky.

What I initially missed was that:

• each part runs in isolation
• each has its own execution context
• each has its own console
• they cannot see each other’s logs

This separation is powerful — but also extremely confusing if you don’t know it exists.

---

😵 The Most Confusing Part: DevTools Debugging

The hardest part wasn't building the UI.
It was debugging DevTools APIs and understanding where my code was actually running.

At one point:

• I had three DevTools windows open for the same page
• my extension was running
• my code was executing
• but my console logs were nowhere to be found

I kept logging everything… and nothing showed up.

It felt broken.
Or worse — undocumented.

---

💡 The Moment of Clarity

The breakthrough came when I understood this:

DevTools extensions have their own execution context.

That means:

• background logs → background context
• content script logs → page context
• DevTools panel logs → only the custom DevTools panel

And those logs appear only after the exact action that triggers them is performed.

Once I:

1. Opened DevTools
2. Opened my custom DevTools panel
3. Triggered the exact event that fired the listener …the logs finally appeared.

Not obvious.
But once this mental model clicked, everything made sense.

---

🧠 What I Actually Learned

This project taught me more than just “how to build a Chrome extension”.

I learned that:

• API contracts are assumptions, not guarantees
• DevTools APIs require mental model alignment, not trial-and-error
• Chrome extensions are less about files — and more about execution boundaries
• Debugging gets easier once your mental model matches reality

Most importantly:

Catching problems early beats handling them gracefully later.

---

🌱 Final Thought

API Inspector doesn’t replace tests.
It doesn’t replace type systems.

But it gives you early visibility —
the moment something changes, not after users complain.

And honestly, building it taught me more about:

• debugging
• architecture
• and developer experience

than many “perfect” tutorial projects ever did.

Comments

[Clemens Herbert]

So well explained! 👌 The architecture decision here makes a lot of sense at scale.

Solid work! ⭐