What a broken endpoint taught me about architecture

The endpoint worked perfectly in every test: correct inputs in, correct outputs out, edge cases covered, integration suite green. Then real traffic arrived and it failed in a way none of the tests had imagined — not because the logic was wrong, but because the world was allowed to send things the tests never considered.

The bug itself was ordinary. The interesting part was where it lived: exactly on the boundary between my system and the outside world, in the place where I had trusted the shape of the data instead of verifying it.

Every test I had written confirmed the behavior for data shaped the way I expected it to arrive. Not one of them asked the more important question: what does this endpoint do with data shaped like nothing we expected?

Validation at the boundary is architecture, not bureaucracy. A strict parser at the edge of a system converts an unknown future failure into a known present rejection — and that difference is the difference between a bug report and a log line.

I now treat the edges of a system — inputs from users, other services, third parties — as hostile by default, with narrow, explicit contracts that fail loudly. The interior can then be elegant, because it only ever sees data that has already been through the door guard.

The irony is that the fix made the code smaller, not bigger. Trusting less means checking once at the boundary instead of defensively everywhere.