Design For Documents: Why your API specs should come before code

Most teams treat documentation as something you write after the fact. That is backwards for anything that ends up as a shared API or a service boundary. Design For Documents flips that assumption. You write the contract first, treat the document as the primary deliverable, and build the implementation to satisfy it. It sounds obvious until you watch a team ship an endpoint that everyone assumed meant something different. I picked this up when we were migrating a monolith into separate services at my old job. The integration debt was real. One service thought status_code 200 meant success, another treated it as a soft acknowledgment. We spent three weeks debugging what should have been caught in a design review.

The core idea is simple. Before you write a single line of backend code, draft the document that describes how the service will be used. This is not the same as writing a spec someone will ignore. The document is the actual source of truth that both the consumer and the provider commit to. It includes the interface definition, data shapes, error semantics, and deployment assumptions. Once it is stable, both sides build against it in parallel. I ran into a specific edge case with one of these documents. We had a service that returned timestamps in different formats depending on whether the caller was internal or external. The document said ISO 8601 everywhere. The implementation did not match because someone assumed the internal path could skip formatting. I caught it during a design review, but only because the document was explicit enough to make the inconsistency visible. My workaround was to add a conformance test that parsed the document and validated every response path against it. That test runs on every CI build now. It prevents drift without requiring manual review of every change. Design For Documents has real limitations. It does not work well for exploratory work where the interface is not yet understood. If you are still figuring out what the service should do, writing a formal contract prematurely locks you into bad decisions. In those cases, throwaway prototypes or interface sketches are more useful than full documents. It also does not replace testing. A well-written document is not the same as a working service. You still need integration tests, contract tests, and performance validation. The document tells you what to build. It does not guarantee the build is correct.

If you are working with a small team where everyone communicates directly, the overhead may not be worth it. I have seen two-person teams skip formal documents entirely and use Slack threads as their interface contract. That works until the team grows past a point where everyone knows everyone else's context. Then the document becomes necessary again. There is no universal rule about when to adopt this. The signal is usually integration fragility. If breaking one service breaks three others in unexpected ways, you probably need better documented contracts.