API Contracts Break in Production. Write Them First.

The most expensive bugs aren't implementation errors-they're contract errors. A team builds an endpoint, the frontend and backend agree on behaviour in a Slack thread, and six months later a field rename breaks a silent consumer. The incident postmortem always includes "we thought this was backward compatible."

Where API Contracts Fail

Most teams document what fields exist and what types they carry. The parts that cause 2am incidents are almost always the same three: error taxonomy (when should a client retry versus fix input?), idempotency (can a payment endpoint safely retry?), and breaking change definition (what counts as breaking before you ship?).

Without these written down, they live in people's heads. When "minor cleanup" happens, an engineer makes a judgment call instead of checking a spec. Removing a field that looks unused. Renaming something that seems internal. Both are breaking changes-or they're not, depending on who's talking about it.

The Spec-First Workflow

The difference between spec-first and regular API development isn't the tools. It's the order. Regular development goes: build, document, ship, break consumer, fix. Spec-first goes: define contract, review contract with consumers, build to contract, validate in CI, ship. That contract review-before code is written-is where conversations about optional versus required fields actually happen. It's almost free at that stage. It's expensive after deployment.

The minimal setup: write an OpenAPI spec for each endpoint. Include what counts as breaking (removing a field, changing a type, making optional required) and what doesn't (adding new optional fields, new endpoints). Run oasdiff in CI to catch breaking changes before they reach review. A 15-minute specification prevents a 2am incident.

Elsewhere this week: Meta is recording employee keystrokes to train AI models, raising questions about what data actually trains these systems. LLMs are being tested for safety robustness with dual red-teaming that exposes weaknesses in both the model and its reward system together. And in the physics world, researchers are observing long-range attraction between like-charged particles-something electrostatic theory says shouldn't happen, suggesting water's molecular structure creates forces current models don't account for.