Contract First or Die Trying: The Only Sane Way to Design APIs

Tue, 16 Dec 2025 00:00:00 +0100

I need to get something off my chest. Something that has been festering in my soul since the first time I joined a project mid-development and asked the fateful question: “Where is the API documentation?”

The answer, invariably, was one of the following:

“Check the Postman collection.” (Translation: a graveyard of 200 requests, half of which are outdated, named things like GET users FINAL v2 (copy))
“Just look at the code.” (Translation: reverse-engineer our spaghetti and good luck)
“We’ll document it later.” (Translation: we will never document it)

Openapi on doismiu - dispatches from the infernal archive

Contract First or Die Trying: The Only Sane Way to Design APIs