DEV Community: guo king

Why Your API Contract Breaks in Production (And How to Fix It in the Spec)

guo king — Wed, 22 Apr 2026 08:11:48 +0000

The most expensive API bugs I've seen weren't implementation bugs. They were contract bugs — cases where the producer and consumer had different beliefs about what the API promised, and nobody wrote it down before the code was shipped.

Here's the pattern: a team builds an endpoint, the frontend and backend agree on the behavior in a Slack thread or a meeting, and the implementation proceeds. Six months later, a field gets renamed as part of a "minor cleanup," a consumer breaks silently, and the incident postmortem includes the sentence "we thought this was backward compatible."

The root cause is almost never malice or carelessness. It's that the contract was implicit — shared understanding that lived in people's heads rather than in a document that both sides could point to.

What an API contract actually is

An API contract is the explicit agreement between a producer and its consumers about:

What fields exist, what they're named, and what types they carry
What the valid inputs are (required vs. optional, validation rules)
What error codes mean and when each one is returned
What "success" looks like at the HTTP level and the payload level
What the retry behavior is — is this operation idempotent?
What the version policy is — when does a change become breaking, and how much notice will consumers get?

Most teams document some of these things. The ones that cause incidents are usually the last three.

The three contract decisions teams skip

1. Error taxonomy

When an operation fails, what does the consumer do next?

If your API returns 400 for validation errors and 400 for business-rule rejections, the consumer can't distinguish between "fix your input" and "this action is blocked for business reasons." They'll implement retry logic that retries unretryable errors, or they'll show the wrong message to the user.

Before implementation, the spec should define:

400 Bad Request    — invalid input; client should fix and retry
409 Conflict       — valid input, business rule blocks; client should not retry
422 Unprocessable  — valid input, data state prevents action; may resolve over time
503 Unavailable    — transient; client should retry with backoff

This is a design decision. Make it in the spec, not in the error handler.

2. Idempotency

Can the consumer safely retry this request if they don't get a response?

Payment endpoints, state-mutation endpoints, and any operation with side effects need an explicit answer. "The backend should handle it" is not an answer — it's a deferred argument.

Spec-first means writing this down before implementation:

POST /orders
Idempotency: Yes
Key: X-Idempotency-Key header (UUID, client-generated)
Window: 24 hours — duplicate requests within 24h return the original response
After window: treated as new request

Now the consumer knows what to send, the backend knows what to store, and QA knows what to test.

3. Breaking change definition

Before you ship your first external-facing version, agree on what counts as breaking:

Breaking (requires version bump, advance notice):

Removing a field
Renaming a field
Changing a field's type
Changing the meaning of an existing status code
Making an optional field required

Non-breaking (can ship without version bump):

Adding a new optional field
Adding a new endpoint
Adding a new enum value (if consumers are built to handle unknown values)
Bug fixes that bring behavior in line with documented behavior

Document this. When "minor cleanup" happens six months from now, the engineer making the change has a checklist, not a judgment call.

The OpenAPI to CI pipeline

Once your contract is written, the best way to protect it is to make breaking changes fail in CI before they reach a reviewer.

The minimal setup:

Generate OpenAPI spec from your implementation (or write it first and validate against it)
Run openapi-diff or oasdiff in CI — fails the build if a breaking change is detected
Run contract tests against a real consumer — Pact or equivalent; the consumer's expectations are versioned alongside the producer's spec

This doesn't prevent all contract breaks. It prevents the ones that nobody caught because they were in a field rename that "obviously" wouldn't affect anything.

The spec-first version of this workflow

The difference between spec-first API development and regular API development isn't the tools. It's the order:

Regular: Build → Document → Ship → Break consumer → Fix

Spec-first: Define contract → Review contract → Build to contract → Validate in CI → Ship

The contract review is where most of the value lives. It's the moment when the consumer team can say "we rely on that field being optional" before the producer team has already built it as required.

That conversation is almost free before implementation. It's expensive after deployment.

A minimal API contract template

If you don't have a spec process yet, start with this for every new endpoint:

Endpoint: POST /v1/[resource]
Purpose: [one sentence]

Request:
  Required fields: [list]
  Optional fields: [list]
  Validation rules: [list]

Response (success):
  Status: 201
  Fields returned: [list]

Response (errors):
  400: [when, what to tell the consumer]
  409: [when, what to tell the consumer]
  503: [when, consumer should retry with backoff]

Idempotency: [yes/no] — if yes, key mechanism and window
Breaking change policy: [link to shared definition]
Version: v1 — changes that break the above require a new version

That's the minimum. It takes 15 minutes to write. The alternative is a 2am incident.

I write about spec-first delivery and API contracts at spec-coding.dev. The API Contract Checklist covers the full pre-release review process.

I Shipped Fewer Bugs After I Started Writing Specs. Heres the Framework

guo king — Wed, 22 Apr 2026 08:11:29 +0000

I Shipped Fewer Bugs After I Started Writing Specs. Here's the Framework

Last March, we had a billing incident that cost us three days. A rounding error in our invoice calculation was silently overcharging customers by fractions of a cent. Not enough for anyone to notice on a single invoice. But multiplied across thousands of transactions over two months, it added up. We had to issue refunds, write a post-mortem, and rebuild trust with a handful of enterprise customers who did the math.

The fix took 20 minutes. The actual bug was a Math.floor() where we needed Math.round() with banker's rounding.

Here's what stung: if anyone had written down "use banker's rounding for currency calculations" before writing the code, this never would have shipped. The developer who wrote it didn't know about our rounding convention. The reviewer didn't think to check. Nobody was wrong. The requirement just lived in one person's head and never made it to the keyboard.

That incident changed how our team builds software.

What spec-first actually means

Spec-first development is simple: before you write code, you write a short document describing what you're building, what you're not building, and how you'll know it works.

It's not waterfall. It's not Big Design Up Front. It's 10 minutes of structured thinking in a text file before you open your editor. Think of it as a conversation with your future self and your reviewers, except you have it before you've sunk 8 hours into an implementation.

The spec travels with the PR. It's a living artifact, not a bureaucratic gate.

A real example: CRM contact deduplication

One of our team members picked up a ticket to build contact deduplication for our internal CRM. On the surface, it seemed straightforward: find duplicate contacts, merge them. Here's the abbreviated spec she wrote before starting:

## Goal
Detect and merge duplicate contacts in the CRM based on email
and phone number matching.

## Non-goals
- Fuzzy name matching (phase 2)
- Automated merging without user confirmation
- Deduplication of company records

## Acceptance Criteria
- Two contacts with the same email (case-insensitive) are flagged as duplicates
- Two contacts with the same phone number (normalized to E.164) are flagged
- User sees a side-by-side comparison and chooses which fields to keep
- Merge preserves all activity history from both records
- Merge is reversible for 30 days

## Edge Cases
- Contact A has email X, Contact B has email X and email Y.
  What happens to email Y after merge?
- Three-way duplicates: A matches B, B matches C, but A doesn't match C
- Contact with 500+ activities: does the merge UI choke?
- Merged contact is referenced in active automation workflows

That spec took about 12 minutes to write. But look at what it caught before a single line of code was written:

The three-way duplicate problem. Without the spec, the developer would have built a pairwise merge and discovered the transitive matching issue during QA. Or worse, in production when a user tried to merge a chain of duplicates and got inconsistent results.

The automation workflow reference. Contacts linked to active automations needed special handling. That requirement wasn't in the ticket. It came out of the developer thinking through edge cases while writing the spec. Without it, merging a contact mid-automation would have broken running workflows.

The reversibility requirement. The original ticket said nothing about undo. But when you write "acceptance criteria," you start thinking about what happens when things go wrong. Thirty days of reversibility turned out to be a key requirement from the customer success team, and the developer discovered this during a quick spec review before starting.

The template

After six months of iteration, our team settled on a lightweight template. Here's the version we use for any feature that takes more than a couple of hours:

# Feature: [Name]
**Author:** [Your name]
**Date:** [Today]
**Status:** Draft / In Review / Approved

## Goal
One paragraph. What are we building and why?

## Non-goals
What are we explicitly NOT doing? (This prevents scope creep.)

## Acceptance Criteria
Numbered list. How do we know this is done?

## Edge Cases
Bullet list. What weird inputs, states, or timing issues could break this?

## Rollout
How does this get to production? Feature flag? Percentage rollout?
Who monitors it?

That's it. Five sections. One page. The non-goals section alone has saved us more rework than any other practice we've adopted. When someone suggests "hey, we should also handle X" during implementation, we check the non-goals list. If X is there, the answer is "not this PR." If it's not there and it should be, we update the spec and have that conversation before writing more code.

I've published the full template with examples if you want to grab it.

Six months of results

We started using specs consistently in October 2025 across a team of eight engineers. Here's what changed by April 2026:

P1 incidents dropped from ~3/month to ~1/month. Not all of that is attributable to specs. We also improved our CI pipeline. But the incidents we did have were operational (infrastructure, scaling) rather than "we built the wrong thing" or "we missed an edge case."

Code review cycles got shorter. Average time from PR open to merge went from 2.1 days to 1.4 days. Reviewers stopped asking "what is this supposed to do?" because the spec was right there. Reviews focused on implementation quality instead of requirements discovery.

Junior engineers ramped faster. Two new hires in January were writing production specs within their second week. The specs gave them a structured way to demonstrate understanding before writing code, and gave senior engineers a concrete artifact to review instead of trying to evaluate whether someone "gets it" from a Slack conversation.

Scope creep became visible. When a feature grew beyond its original spec, we could point to the document and say "this is new scope. Do we want to update the spec or save it for a follow-up?" Before specs, scope crept silently until the PR was twice the expected size.

The biggest surprise: specs made estimation better. When you force yourself to list acceptance criteria and edge cases upfront, you have a much clearer picture of the actual work. Our sprint velocity predictions got noticeably more accurate, not because we got better at estimating, but because we got better at understanding what we were estimating.

Getting started

If you've never written a spec before, don't try to change your whole team overnight. Start with yourself, on one feature. Pick something you're about to build that has at least a couple of moving parts. Spend 10 minutes filling in the template above. Share it with whoever would review your PR and ask: "Does this match your understanding?"

That one conversation will tell you whether spec-first development is worth adopting more broadly. In my experience, it always is.

I've written a complete guide to spec-first development that covers the philosophy, the process, and the common objections. And the template is free to download. Take it, modify it, make it yours.

Daniel Marsh is a software engineer and the author of spec-coding.dev, a resource for teams adopting spec-first development.

10 Software Spec Mistakes That Cause Production Incidents (With Fixes)

guo king — Wed, 22 Apr 2026 08:10:58 +0000

After 12 years in B2B SaaS — and too many postmortems — I've noticed that most production incidents trace back to a decision that wasn't made in the spec. Not a coding error. A specification gap.

Here are the 10 mistakes I see most often, what the symptom looks like, and how to fix each one before implementation starts.

1. Acceptance criteria that can't be tested

Symptom: QA closes the ticket as "passed" but the feature behaves differently than product expected.

The mistake:

The user should see a confirmation message after submitting.

The fix:

Given a valid form submission, when the user clicks Submit, then a green banner appears at the top of the page with the text "Your changes have been saved" and remains visible until the user navigates away or dismisses it.

Acceptance criteria are a contract between product and QA. If QA has to ask the author what "confirmation" means, the spec didn't do its job.

2. Non-goals that don't name anything

Symptom: Engineering builds something adjacent to the spec because the boundary wasn't explicit.

The mistake:

Out of scope: internationalization and advanced settings.

The fix:

Out of scope for this release: (1) translated UI strings — English only; (2) per-user notification preferences — all users receive the same defaults; (3) bulk operations — only single-record edits are supported. A reviewer can reject this change if any of these appear in the implementation.

The non-goal should be specific enough that a reviewer can use it to push back.

3. No named decision owner

Symptom: Scope creep during implementation because nobody was authorized to say "that's out."

The fix: Every spec should have one named person who can approve scope changes. Not a committee. One person. If that person is unavailable, a named backup.

4. "Handled elsewhere" for failure paths

Symptom: An edge case hits production and ops discovers there's no fallback, no log, and no rollback path.

The mistake:

Error handling will be managed by the existing error middleware.

The fix: Name the specific failure modes and what happens in each:

If the payment processor times out after 10 seconds: return HTTP 503, log payment.timeout with order ID, do NOT charge the card, surface "Payment unavailable — please try again" to the user. Do not retry automatically.

5. Missing rollback definition

Symptom: A deployment goes wrong and nobody agrees on what "rollback" means, so the incident runs 3x longer than it should.

The fix: Before implementation, answer: if this change is reverted, what exactly happens?

Code revert only?
Config flag flip?
Database migration that needs to be reversed?
Data that needs to be repaired?

If rollback requires data repair, that repair script should be written before the feature ships.

6. Acceptance criteria that only cover the happy path

Symptom: QA testing passes 100%, but 3 edge cases surface in production week one.

The fix: For every main-flow scenario, write at least one failure scenario and one boundary scenario.

Happy path: Given a valid user, when they submit, then success.
Failure path: Given an expired session, when they submit, then redirect to login with the form state preserved in session.
Boundary: Given a user with exactly 0 remaining credits, when they try to submit, then show the upgrade prompt before the form is processed.

7. Ambiguous authorization rules

Symptom: A user can access or modify something they shouldn't be able to. Or they can't do something they should be able to.

The mistake:

Only authorized users can edit this record.

The fix:

Edit access requires: (1) the user is the record owner, OR (2) the user has the admin role in the same organization. Users with viewer role can read but not edit. Requests from users outside the record's organization are rejected with 403, regardless of their role.

8. No stop-loss threshold for the release

Symptom: A feature causes elevated error rates after deployment. Nobody knows whether to roll back or wait, so the on-call engineer makes a judgment call at 1am.

The fix: Name the threshold before the release:

Roll back automatically if: error rate on /checkout exceeds 2% over a 5-minute window, OR payment processor timeout rate exceeds 5%, OR any P0 alert fires within 2 hours of deployment. The on-call engineer does not need approval to roll back if these thresholds are hit.

9. "Friendly" or "reasonable" as a spec term

Symptom: Engineering and design interpret "friendly error message" differently. Or "reasonable performance" means 200ms to one person and 2 seconds to another.

The fix: Replace every vague term with a testable one.

"friendly" -> specific message text or message category
"reasonable" -> explicit metric with threshold
"fast" -> p95 latency under X ms at Y concurrent users
"handled" -> specific behavior enumerated

10. Spec written after the code

Symptom: The spec reads like documentation of what was built, not a description of what should be built. Nobody reviewed it before implementation.

The fix: This one is structural, not a wording fix. The spec needs to exist — and be reviewed — before implementation starts. The review is where the expensive conversations happen cheaply.

The spec's job is not to describe decisions after they're made. It's to force decisions before they're expensive.

The common thread

Every mistake on this list has the same root cause: a decision that should have been made explicitly in the spec was left implicit, and the team discovered the gap somewhere more expensive — in review, in testing, or in production.

Spec-first development doesn't mean longer documents. It means making the right decisions earlier, in writing, where they can be challenged before they're coded.

I publish practical spec-first guides and free templates at spec-coding.dev. The Spec Review Checklist covers the pre-implementation review in detail.

I Shipped Fewer Bugs After I Started Writing Specs — Here's the Framework

guo king — Wed, 01 Apr 2026 09:48:53 +0000

I Shipped Fewer Bugs After I Started Writing Specs — Here's the Framework

Last March, we had a billing incident that cost us three days. A rounding error in our invoice calculation was silently overcharging customers by fractions of a cent. Not enough for anyone to notice on a single invoice — but multiplied across thousands of transactions over two months, it added up. We had to issue refunds, write a post-mortem, and rebuild trust with a handful of enterprise customers who did the math.

The fix took 20 minutes. The actual bug was a Math.floor() where we needed Math.round() with banker's rounding.

Here's what stung: if anyone had written down "use banker's rounding for currency calculations" before writing the code, this never would have shipped. The developer who wrote it didn't know about our rounding convention. The reviewer didn't think to check. Nobody was wrong — the requirement just lived in one person's head and never made it to the keyboard.

That incident changed how our team builds software.

What spec-first actually means

Spec-first development is simple: before you write code, you write a short document describing what you're building, what you're not building, and how you'll know it works.

It's not waterfall. It's not Big Design Up Front. It's 10 minutes of structured thinking in a text file before you open your editor. Think of it as a conversation with your future self and your reviewers — except you have it before you've sunk 8 hours into an implementation.

The spec travels with the PR. It's a living artifact, not a bureaucratic gate.

A real example: CRM contact deduplication

## Goal
Detect and merge duplicate contacts in the CRM based on email
and phone number matching.

## Non-goals
- Fuzzy name matching (phase 2)
- Automated merging without user confirmation
- Deduplication of company records

## Acceptance Criteria
- Two contacts with the same email (case-insensitive) are flagged as duplicates
- Two contacts with the same phone number (normalized to E.164) are flagged
- User sees a side-by-side comparison and chooses which fields to keep
- Merge preserves all activity history from both records
- Merge is reversible for 30 days

## Edge Cases
- Contact A has email X, Contact B has email X and email Y —
  what happens to email Y after merge?
- Three-way duplicates: A matches B, B matches C, but A doesn't match C
- Contact with 500+ activities — does the merge UI choke?
- Merged contact is referenced in active automation workflows

That spec took about 12 minutes to write. But look at what it caught before a single line of code was written:

The three-way duplicate problem. Without the spec, the developer would have built a pairwise merge and discovered the transitive matching issue during QA — or worse, in production when a user tried to merge a chain of duplicates and got inconsistent results.

The reversibility requirement. The original ticket said nothing about undo. But when you write "acceptance criteria," you start thinking about what happens when things go wrong. Thirty days of reversibility turned out to be a key requirement from the customer success team — the developer discovered this during a quick spec review before starting.

The template

After six months of iteration, our team settled on a lightweight template. Here's the version we use for any feature that takes more than a couple of hours:

# Feature: [Name]
**Author:** [Your name]
**Date:** [Today]
**Status:** Draft / In Review / Approved

## Goal
One paragraph. What are we building and why?

## Non-goals
What are we explicitly NOT doing? (This prevents scope creep.)

## Acceptance Criteria
Numbered list. How do we know this is done?

## Edge Cases
Bullet list. What weird inputs, states, or timing issues could break this?

## Rollout
How does this get to production? Feature flag? Percentage rollout?
Who monitors it?

I've published the full template with examples if you want to grab it.

Six months of results

We started using specs consistently in October 2025 across a team of eight engineers. Here's what changed by April 2026:

P1 incidents dropped from ~3/month to ~1/month. Not all of that is attributable to specs — we also improved our CI pipeline. But the incidents we did have were operational (infrastructure, scaling) rather than "we built the wrong thing" or "we missed an edge case."

Junior engineers ramped faster. Two new hires in January were writing production specs within their second week. The specs gave them a structured way to demonstrate understanding before writing code — and gave senior engineers a concrete artifact to review instead of trying to evaluate whether someone "gets it" from a Slack conversation.

Scope creep became visible. When a feature grew beyond its original spec, we could point to the document and say "this is new scope — do we want to update the spec or save it for a follow-up?" Before specs, scope crept silently until the PR was twice the expected size.

The biggest surprise: specs made estimation better. When you force yourself to list acceptance criteria and edge cases upfront, you have a much clearer picture of the actual work. Our sprint velocity predictions got noticeably more accurate — not because we got better at estimating, but because we got better at understanding what we were estimating.

Getting started

That one conversation will tell you whether spec-first development is worth adopting more broadly. In my experience, it always is.

I've written a complete guide to spec-first development that covers the philosophy, the process, and the common objections. And the template is free to download — take it, modify it, make it yours.

Daniel Marsh is a software engineer and the author of spec-coding.dev, a resource for teams adopting spec-first development.

What Is Spec-First Development? (Complete Guide)

guo king — Sat, 14 Mar 2026 02:43:23 +0000

Originally published at spec-coding.dev

Spec-first development becomes clearer when the team makes the hidden
decisions visible before coding starts. This article focuses on those
decisions and why they matter in delivery.

## 1. Why Teams Usually Get This Wrong

The problem appears the moment more than one role depends on the answer.
Product wants speed, engineering wants boundaries, QA wants testability, and
operations wants something that can be rolled back without improvisation. If
the spec never resolves those tensions, the work moves downstream as rework.

The real decision behind spec-first is ownership. Who approves the
boundary? Who validates acceptance criteria? Who can stop a rollout? Without
those answers in writing, teams ship with blurred accountability.

## 2. A Concrete Delivery Situation

Test your spec against one realistic delivery path. Ask:

What can the reviewer reject?
What can the tester verify?
What can the operator roll back?

If the document cannot answer those three angles, it is not ready. Stop asking
whether the team "understands the idea" and start asking whether the written
spec would survive handoff.

## 3. What the Spec Needs to Say Out Loud

A stronger spec is not longer by accident — it is more explicit exactly where
projects tend to drift. At minimum:

The intended outcome, explicit non-goals, and the decision owner for scope changes
Acceptance criteria that can be judged pass or fail without tribal knowledge
Failure behavior, fallback paths, and which logs or metrics will surface them after release

## 4. Acceptance Criteria That Remove Guesswork

Given the approved scope and dependencies When the team executes the primary flow Then success can be verified with a concrete result and observable evidence
Given an exception, retry, or permission boundary is hit When the system takes the fallback path Then the user-facing behavior and operational response remain explicit

The goal is not to force every team into the same wording. The goal is to
force decisions about input, trigger, and expected behavior while there is
still time to change course cheaply.

## 5. Review Questions Before Implementation Starts

Which decision would still be ambiguous to a reviewer seeing the change for the first time?
Can QA derive the main-flow, failure-path, and regression cases without interviewing the author?
If the release fails, does the document tell operations what to watch and when to stop?

If you cannot answer these without a side conversation, the draft is still
carrying unpriced uncertainty.

## 6. Rollout, Monitoring, and Rollback

Good specs do not stop at merge readiness. They tell the team how to release
safely:

Stage to the smallest useful audience first — don't treat review approval as a substitute for runtime evidence
Name the stop-loss threshold before release: error rate, latency, data mismatch, or override volume
Record what rollback actually means: code revert, config switch, job pause, or data repair

## 7. Common Mistakes

Treating scope as obvious and leaving the real policy decision for implementation review
Hiding risky edge behavior behind vague phrases like reasonable, friendly, or handled elsewhere
Publishing a document that sounds complete but never states how success or rollback will be judged

## 8. When to Go Deep vs. Stay Lightweight

The right amount of detail is the amount that prevents expensive invention
later. If a missing sentence would force engineering, QA, or operations to
guess — that sentence belongs in the spec.

What matters is not document length. What matters is whether the document
prevents the team from rediscovering the same decision in implementation,
testing, and release review.

## 9. Final Takeaway

Spec-first development becomes easier once the spec names the risky decisions
early enough for someone to challenge them. That is the practical value:
less improvisation, fewer surprises in review, and cleaner evidence when it
is time to ship.

Daniel Marsh is a senior software engineer with 12 years of experience,
specializing in spec-first development. More articles at
spec-coding.dev.