DEV Community: Prasad MK

Locking Down the Pipeline: Enforcing Contract Integrity Against Autonomous AI Agents

Prasad MK — Sat, 30 May 2026 18:01:22 +0000

Locking Down the Pipeline: Enforcing Contract Integrity Against Autonomous AI Agents (Part 4)

Parts 1 through 3 assumed one thing: a human is in the loop. A developer runs the local gate, reads the failure, and makes a deliberate decision. Even in Part 3, the vibe coder is still present. They feed the spec to the AI, read the output, and decide whether to push.

Part 4 removes that assumption entirely.

Autonomous AI agents, tools like Devin, AutoGPT, or custom LangChain pipelines, can now write code, run tests, interpret failures, and open pull requests without a human reviewing each step. This is not a future scenario. Teams are already running these workflows today.

The drift problem does not disappear in this environment. It accelerates. And it gets a new capability: the ability to cover its own tracks.

Why Autonomous Agents Break the Framework

An AI agent tasked with a refactor will do whatever it takes to satisfy the local objective. If it changes the pagination logic and the REST Assured test fails, it does not stop and ask a developer for guidance. It looks at the failure, determines that the test is an obstacle, and rewrites the assertion to make the build green.

From the agent's perspective, the task is complete. The build passes. The PR opens.

From the system's perspective, the contract was just silently redefined by an automated process that had no awareness of downstream consumers, no knowledge of the versioning rules from Part 2, and no constraint preventing it from touching protected files.

The governance framework built in Parts 1 and 2 relied on human judgment at the decision point. CODEOWNERS works when a human reviewer looks at the PR. A verbal rule about not mutating tests works when a developer reads it and understands why it exists.

Neither of these holds when the contributor is an agent running at machine speed.

The Solution: Programmatic Rails, Not Prose Rules

You cannot solve an automated problem with a social solution. Telling an AI agent to follow the rules in its system prompt is not a governance strategy. Context windows drift. Model updates change behavior. Prompt instructions get deprioritized when the agent is focused on satisfying a local objective.

The framework needs to be deterministic. The rails need to be structural. The enforcement needs to happen at the system level, not the prompt level.

Three layers make this work.

Layer 1: The Constraint File as a Machine-Readable Contract

The first layer moves the governance rules out of prose and into a structured file that the agent is required to parse before acting.

Create a .ai-rules.json file at the root of the repository:

{
  "repository_constraints": {
    "api_versioning": "STRICT",
    "breaking_changes": "NEVER_MUTATE_EXISTING_TESTS",
    "known_domain_rules": {
      "/api/v1/users": {
        "pagination_base": 1,
        "enforced_by": "UserWorkflowVerificationTest.java"
      }
    }
  }
}

This file does two things. It tells the agent exactly which domain rules govern each endpoint, and it explicitly names the test file that enforces each rule. When the agent is tasked with modifying anything under /api/v1/users, it must parse known_domain_rules first and treat those constraints as non-negotiable inputs, not suggestions.

The critical shift here is the difference between a rule the agent reads and a rule the agent loads as structured data. Prose in a system prompt gets weighed against the agent's objective. A JSON constraint file that the orchestration script injects into the agent's context window before execution is a boundary condition, not a preference.

Commit this file to the repository and version it alongside the API. When the contract evolves, the constraint file evolves with it in the same PR. The rules are traceable, reviewable, and visible to every contributor, human or automated.

Layer 2: The Pre-Commit Hook as the Deterministic Bouncer

The constraint file sets expectations. The pre-commit hook enforces them at the moment the agent tries to commit.

This is the most important layer because it operates entirely outside the agent's control. No matter what the agent decided to do, no matter what it changed, the hook runs before the commit is allowed to proceed.

#!/bin/bash
# Contract integrity check - runs before every commit

# Step 1: Run the protected REST Assured contract tests
mvn test -Dtest=UserWorkflowVerificationTest

if [ $? -ne 0 ]; then
  echo "ERROR: Contract tests failed. The commit is blocked."
  echo "Fix the underlying code. Do not modify the test assertions."
  exit 1
fi

# Step 2: Verify the agent did not touch the protected test file
if git diff --name-only | grep -q "UserWorkflowVerificationTest.java"; then
  echo "ERROR: AI Agent attempted to modify a protected contract test."
  echo "Functional changes require a new API version or architectural sign-off."
  exit 1
fi

The hook does two things in sequence. It runs the contract tests and blocks the commit if they fail. Then it checks the git diff and blocks the commit if the agent touched the protected test file at all, regardless of whether the tests pass.

That second check is the one that matters most. An agent that rewrites the assertion to make a failing test pass will produce a green test result. Without the diff check, the first gate would not catch it. The combination of both checks closes that gap entirely.

If the agent cannot commit, it cannot open a PR. If it cannot open a PR, the drift never reaches the repository.

Layer 3: The Coder and Auditor Pattern

The two layers above are defensive. They block bad commits from landing. The third layer is diagnostic. It determines why a failure happened and instructs the agent on how to fix it correctly.

The pattern is a separation of roles. Agent A is the Coder. It writes and refactors code. Agent B is the Auditor. It reviews the delta when the gate fails. These are two distinct LLM instances with different objectives, and they must never be the same instance self-reviewing its own output.

The reason this separation matters is the same reason a developer should not approve their own PR. An agent asked to both write code and verify its correctness will optimize for satisfying its own objective. The Auditor needs to be a genuinely independent process with a different prompt, a different focus, and explicit authority to reject the Coder's output.

When the pre-commit hook fails, the orchestration layer triggers the Auditor with this prompt:

System: You are an automated architectural gatekeeper.
Your job is to determine if a code change introduced a breaking
regression or a valid feature expansion.

Input Artifacts:
1. Git diff of the change: [Insert diff]
2. Test failure log: [Insert REST Assured terminal output]
3. Enforced rules schema: [Insert .ai-rules.json contents]

Task: Analyze whether the code change violates any constraint
defined in the rules schema. If it does, generate a rejection
log that instructs the Coder agent to revert the specific change
and fix the underlying logic.

Constraint: Under no circumstances should the test suite assertions
be modified. The tests define the contract. The code must conform to them.

The Auditor does not fix the code. It produces a rejection log that describes exactly what the Coder did wrong and what it needs to do differently. The Coder then receives that rejection log as its next input and retries.

This loop continues until the pre-commit hook passes cleanly, meaning the contract tests are green and the protected test files are untouched.

How the Full Framework Holds Together

Stepping back across all four parts, the same contract flows through every layer.

The Spring Boot application exposes its live OpenAPI spec at /v3/api-docs. REST Assured derives its tests from that contract. Postman derives its collections from that contract. CODEOWNERS enforces that nobody modifies the core test files without cross-team review. API versioning ensures that behavioral changes ship as new endpoints, not as silent mutations to existing ones. The .ai-rules.json file encodes the domain rules as machine-readable constraints. The pre-commit hook enforces those constraints at commit time, regardless of whether the contributor is human or automated. The Auditor agent closes the diagnostic loop when something goes wrong.

At no point does the framework rely on trust, memory, or discipline. Every layer is structural. Every enforcement is deterministic. The contract is defined once, in the code, and every tool downstream, whether it is a developer, a vibe coder, or an autonomous agent, operates within the same boundaries.

Closing the Series

The zero-drift problem is not a tooling problem. The tools, REST Assured, Postman, Git, OpenAPI, were always capable of solving it. The missing piece was a coherent framework that connected them into a single chain of enforcement, from the individual developer's local machine all the way to an autonomous agent operating without human oversight.

That chain is now complete. Start with Part 1 today. The local loop costs less than an hour to set up and pays back immediately. Add the governance layer from Part 2 when the team grows. Introduce the AI prompt discipline from Part 3 when AI tools enter the workflow. Apply the programmatic rails from Part 4 when agents start opening PRs on their own.

The build should be green because the contract is intact. Every time. At every scale.

The Zero-Drift API Series

Intro: The Zero-Drift API Series: Stop Trusting a Green Build You Can't Explain
Part 1: A Guide to Stop Breaking Merges: Unifying Postman and REST Assured in Spring Boot
Part 2: Who Approved This Change? Managing API Contracts and Test Rot in Large Engineering Teams
Part 3: The AI Superpower: How Vibe Coders Use OpenAPI as a Semantic Anchor
Part 4: Locking Down the Pipeline: Enforcing Contract Integrity Against Autonomous AI Agents

The AI Superpower: How Vibe Coders Use OpenAPI as a Semantic Anchor

Prasad MK — Sat, 30 May 2026 17:53:16 +0000

The AI Superpower: How Vibe Coders Use OpenAPI as a Semantic Anchor (Part 3)

Parts 1 and 2 solved the drift problem for developers who write code deliberately. A local REST Assured gate, Postman wired to the live spec, CODEOWNERS enforcing review on core contracts, and API versioning as the hard rule when behavior changes.

Now introduce a different kind of contributor. A vibe coder.

A vibe coder is not a junior developer making rookie mistakes. They are often highly productive engineers who use AI tools like Cursor, Copilot, or a plain LLM chat window to generate, refactor, and iterate on code rapidly. The focus is on intent and outcome, not on typing syntax. The speed is real. So is the risk.

The Problem AI Introduces

An AI model generating code has no awareness of your running system. It does not know that your pagination is 1-based, that a specific field was renamed three sprints ago, or that a downstream mobile client breaks if a response envelope changes shape.

It knows patterns. It knows what a Spring Boot controller generally looks like. It knows what a TypeScript fetch service should probably contain. When it does not have exact information, it fills the gap with a confident-looking guess.

This is called a hallucinated contract. The generated code compiles. The types look plausible. The field names are reasonable. And the first time it runs against your actual API, something quietly breaks because the AI invented a payload shape that does not match reality.

The drift problem from Part 1 gets faster and more confident with AI in the loop. Without a semantic anchor, the AI is just a very fluent source of test rot.

The Fix: Feed the Spec, Not Just the Prompt

The OpenAPI spec that has been doing all the work in Parts 1 and 2 is the answer here too. Instead of asking the AI to guess your contract, you hand it the exact live definition from your running application and treat it as a non-negotiable constraint.

When the AI works from /v3/api-docs, it is no longer guessing. It knows the exact endpoint paths, the required fields, the optional fields, the data types, the pagination parameters, and the response envelope shape. Every piece of code it generates is grounded in what the system actually does right now.

This is the semantic anchor. The same single source of truth that keeps Postman and REST Assured in sync becomes the context that keeps AI-generated code from drifting before it is even written.

Three Prompts That Close the Loop

The following prompts cover the three stages where AI intersects with the zero-drift workflow.

Prompt 1: Generate the REST Assured Test Suite from the Live Spec

Instead of writing boilerplate test classes by hand, boot the application, grab the OpenAPI JSON from http://localhost:8080/v3/api-docs, and hand it to the AI with this prompt.

System: You are an expert backend QA engineer.
I will provide my local application's raw OpenAPI/Swagger JSON specification.

Task: Generate a complete REST Assured integration test class in Java
using @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT).

Rules:
1. Use standard given().when().then() syntax.
2. Every endpoint in the specification must have at least one contract
   validation test covering the status code and core payload fields.
3. Implement random local port setup using @LocalServerPort.

Here is the OpenAPI specification JSON:
[Paste http://localhost:8080/v3/api-docs output here]

The AI now generates tests that match your actual endpoints, your actual field names, and your actual response structure. Not a plausible approximation of them.

This also means the tests are immediately runnable. There is no cleanup pass to fix field names the AI invented.

Prompt 2: Debug a Failing Test Without Reading the Stack Trace

When a local REST Assured test fails after an AI-assisted refactor, the natural instinct is to dig through the stack trace manually. There is a faster path. Feed the failure back to the AI with the relevant controller code and let it diagnose itself.

Context: My local REST Assured test suite just failed during a local check.

The Error:
[Paste the JUnit failure output here, e.g.:
 JSON path currentPage expected 1 but was 2]

The Relevant Controller/Service Code:
[Paste your Spring Boot Controller or Service class here]

Task: Analyze the code and the test failure. Identify where the contract
logic diverged. Fix the underlying Java code to restore backward
compatibility with the expected contract. Explain exactly why the
runtime behavior shifted.

Constraint: Do not modify the test assertion. The test reflects the
contract. The code must conform to it.

The constraint at the end is critical and worth stating explicitly every time. Without it, the AI's default instinct is to make the test pass by any means available, including rewriting the assertion. That is exactly the silent mutation problem from Part 2. The prompt structure prevents it.

Prompt 3: Generate Frontend Code with Zero Payload Drift

When a vibe coder moves to building a UI component or a mobile client that consumes the Spring Boot API, the same anchor applies. Do not let the AI guess the payload shape. Give it the spec.

Context: I am building a frontend component in React/TypeScript that
communicates with my Spring Boot backend.

Input: Here is the live contract definition from my backend:
[Paste http://localhost:8080/v3/api-docs output here]

Task: Generate a TypeScript Fetch/Axios service and the corresponding
interface types for the /api/v1/users endpoint.

Rules:
1. All property names must match the schema definitions exactly.
2. Respect optional and required field flags from the spec.
3. Pagination handling must be based strictly on the parameters
   defined in the specification. Do not assume defaults.

The result is a TypeScript service that matches the backend contract on the first generation. No runtime surprises when the frontend hits the actual API. No field name mismatches discovered in a browser console after a deploy.

Why This Matters Beyond Convenience

There is a deeper point here worth stating plainly.

The zero-drift framework in Parts 1 and 2 is built on one principle: the contract lives in the code, and everything else derives from it. REST Assured derives from it. Postman derives from it. CODEOWNERS enforces that nobody silently redefines it.

When AI enters the workflow without this anchor, it introduces a third source of truth, which is the model's best guess. That guess is invisible, confident, and wrong in ways that are hard to detect until something breaks downstream.

Feeding the spec into the AI does not slow down the vibe coder's workflow. It makes the output trustworthy on the first pass, which is actually faster than the debug cycle that follows a hallucinated contract.

The local REST Assured gate from Part 1 remains the final verification. If the AI introduced drift anywhere, the gate catches it in under five seconds. The developer does not need to know exactly what the AI got wrong. They feed the failure back with Prompt 2, fix the code, and run the gate again.

The loop is fast. The contract stays clean. The AI becomes an accelerator rather than a liability.

What Comes Next

Parts 1 through 3 handle the developer-in-the-loop case, whether they are writing code manually, working in a large team with governance constraints, or using AI tools to generate at speed.

Part 4 removes the developer from the loop entirely. When autonomous AI agents are opening pull requests without a human reviewing each change, the governance framework needs to be deterministic and programmatic. Pre-commit hooks, constraint files baked into the repository, and a multi-agent Coder/Auditor pattern that treats the AI like an untrusted contributor.

Part 4: Locking Down the Pipeline: Enforcing Contract Integrity Against Autonomous AI Agents

The Zero-Drift API Series

Intro: The Zero-Drift API Series: Stop Trusting a Green Build You Can't Explain
Part 1: A Guide to Stop Breaking Merges: Unifying Postman and REST Assured in Spring Boot
Part 2: Who Approved This Change? Managing API Contracts and Test Rot in Large Engineering Teams
Part 3: The AI Superpower: How Vibe Coders Use OpenAPI as a Semantic Anchor
Part 4: Locking Down the Pipeline: Enforcing Contract Integrity Against Autonomous AI Agents

Who Approved This Change? Managing API Contracts and Test Rot in Large Engineering Teams

Prasad MK — Sat, 30 May 2026 17:39:22 +0000

Who Approved This Change? Managing API Contracts and Test Rot in Large Engineering Teams (Part 2)

Part 1 established a clean local loop. REST Assured runs in under five seconds on the developer's machine. Postman pulls from the live OpenAPI spec. The gate is reliable, and the contract is grounded in actual code.

Now add 50 developers to that picture.

Suddenly the local loop is not enough. One developer's intentional optimization is another downstream team's production regression. And here is the uncomfortable truth: the test suite itself becomes the attack surface.

The Trap Nobody Talks About

When a REST Assured test fails because a developer changed API behavior, there are two ways to make it green again. Fix the code, or fix the test.

Fixing the test is faster. It feels harmless. The build goes green. The PR merges. And somewhere downstream, a team that depended on the original behavior starts seeing failures they did not cause and cannot explain.

This is not a discipline problem. It is a structural one. When a single developer can silently redefine an API contract by updating an assertion, the test suite stops being a gate and starts being a liability.

The Opposite Trap Is Just as Bad

The instinctive overcorrection is to declare all existing tests immutable. Nobody touches them. Ever. Only new tests get added.

This sounds safe. It is not.

When an API genuinely needs to evolve, the old test stays active and stays failing. Teams start using @Ignore just to get deployments through. The test suite becomes a graveyard of outdated assertions that nobody trusts and nobody deletes. This is test rot, and it is just as damaging as silent contract mutation, just slower.

The dilemma looks like this:

Approach	The Benefit	The Trap
Never change old tests	Prevents silent contract rewrites	Causes permanent build failures when changes are intentional. The suite becomes a historical graveyard.
Freely modify existing tests	Keeps the suite clean and passing	One developer can redefine the contract for the entire organization without downstream teams knowing.

Neither extreme works at scale. The answer is a governance layer that distinguishes between the two cases explicitly.

The Architectural Solution: Three Levers

You do not need to throw away REST Assured or install a complex contract broker to solve this. Three levers, used together, handle the governance problem with tooling teams already have.

Lever 1: API Versioning as a Hard Rule

When a functional change modifies payload structure, field behavior, or pagination logic, the existing endpoint is not touched. It stays exactly as it is, along with its REST Assured tests.

The change ships under a new version.

/api/v1/users and its test suite remain intact and passing. /api/v2/users is introduced with a brand new test class that reflects the new behavior. Downstream teams consuming v1 are never broken. They migrate to v2 on their own timeline.

This rule eliminates the core dilemma entirely. There is no decision to make about whether to update an old test, because the old endpoint and its tests are never touched.

Lever 2: CODEOWNERS to Enforce Review on Core Contracts

GitHub and GitLab both support a CODEOWNERS file that assigns mandatory reviewers to specific directories. This is the enforcement mechanism for the versioning rule.

Place the core REST Assured contract tests under a protected path:

src/test/java/com/yourorg/contracts/

Then add a CODEOWNERS entry:

src/test/java/com/yourorg/contracts/ @api-architecture-team

Now any PR that modifies a file inside that directory cannot merge without explicit approval from the API architecture group. A developer can freely add new test files for new features anywhere else. But touching an existing contract test requires a deliberate, cross-team sign-off.

The gate is no longer social. It is structural.

Lever 3: Deprecation Windows Instead of Deletion

When old functionality genuinely needs to retire, the process is not a silent test deletion. It is a staged, visible wind-down.

Mark the old endpoint as @Deprecated in the Spring Boot controller. Log a deprecation warning on every call so downstream teams see it in their monitoring. Schedule the removal for a future sprint with a communicated deadline. When that sprint arrives, the old endpoint and its REST Assured tests are deleted together, in the same PR, with full visibility.

Nobody is surprised. Nobody discovers a broken contract in production. The retirement is as explicit as the original contract.

When You Need More: Consumer-Driven Contract Testing

The three levers above handle the majority of real-world cases without additional infrastructure. But if your organization has many independent teams consuming the same APIs, and the coordination cost of manual review is becoming a bottleneck, the next step is Consumer-Driven Contract Testing using Pact or Spring Cloud Contract.

The model works like this. Each downstream team that consumes an API publishes a consumer contract that explicitly declares what it expects. When Team A's developer makes a change that affects /api/v1/users, the CI pipeline automatically pulls all active consumer contracts from a shared broker and runs them against the new code. If any consumer contract fails, the merge is blocked and the affected team is notified before anything ships.

The key difference from the lever approach is that enforcement becomes fully automated. No human reviewer needs to catch the conflict. The pipeline catches it.

This is the right investment when teams are large enough that CODEOWNERS review becomes a bottleneck, or when downstream consumers are external and cannot be coordinated manually.

What This Looks Like in Practice

A developer on Team A refactors the user pagination logic and opens a PR.

Without governance: the test fails, they update the assertion, CI goes green, Team B finds out when their service breaks in staging.

With governance: the test fails. The CODEOWNERS rule blocks the PR from merging without architecture review. The reviewer looks at the change, determines it is a functional behavioral shift, and asks the developer to version the endpoint. /api/v2/users is introduced. Team B is notified of the new version. Team A ships. Nobody breaks.

The difference is not more process. It is the right structure in the right place.

What Comes Next

At this point the framework handles individual developers and distributed teams. The contract is protected, the versioning rule is enforced, and the governance layer is structural rather than cultural.

Part 3 introduces a different kind of contributor: AI-assisted developers using tools like Cursor or Copilot, who are generating code faster than any review process was designed to handle. The same OpenAPI spec that anchors Postman and REST Assured becomes the semantic anchor that keeps AI-generated code from hallucinating payload shapes and silently drifting from the contract.

Part 3: The AI Superpower: How Vibe Coders Use OpenAPI as a Semantic Anchor

The Zero-Drift API Series

A Guide to Stop Breaking Merges: Unifying Postman and REST Assured in Spring Boot

Prasad MK — Sat, 30 May 2026 17:32:41 +0000

A Guide to Stop Breaking Merges: Unifying Postman and REST Assured in Spring Boot (Part 1)

Every engineering team hits this wall eventually. A developer updates an endpoint, verifies it quickly on their local machine, and opens a pull request. It merges cleanly. Then the deployment pipeline breaks, or worse, a silent contract regression slips past CI entirely and lands in staging or production.

This is the Merge Bottleneck. The root cause is almost never a lack of discipline. It is a structural flaw in how validation workflows are separated.

Manual exploratory testing in Postman does not scale to guard git merges. A detached REST Assured suite that nobody keeps in sync with the actual API introduces test drift. Two tools, two descriptions of the same system, diverging silently over time.

This guide fixes that by making the Spring Boot application itself the single source of truth, and wiring both Postman and REST Assured to consume from it directly.

The Core Strategy: Code-First Sync

Spring Boot, with the springdoc-openapi dependency, exposes a live OpenAPI specification at /v3/api-docs whenever the application is running. That endpoint is your contract. Everything else derives from it.

Both Postman and REST Assured point at the same running application. When the code changes, both tools see the change immediately. There is no manual sync step, no documentation page to update, and no drift.

Step 1: Establish the Local Automated Gate

The primary safety net needs to run on the developer's machine in seconds, before any CI queue is involved. Waiting for a pipeline to tell you the build is broken is already too late in the feedback loop.

The setup uses @SpringBootTest with RANDOM_PORT. This spins up a real, isolated instance of the application, runs REST Assured verifications against it, and tears down the context when the test completes. Nothing is mocked. The full application stack runs.

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class UserWorkflowVerificationTest {

    @LocalServerPort
    private int port;

    @BeforeEach
    public void setUp() {
        RestAssured.baseURI = "http://localhost";
        RestAssured.port = port;
    }

    @Test
    public void verifyUserCreationContract() {
        RestAssured.given()
            .contentType("application/json")
            .body("{\"name\": \"Dev Team\", \"email\": \"dev@company.com\"}")
        .when()
            .post("/api/v1/users")
        .then()
            .statusCode(201);
    }
}

This test is the gate. If it is red, the developer does not push.

Step 2: Wire Postman to the Live Local Spec

When a developer needs to explore edge cases or visually inspect a payload, they should not be manually constructing JSON from memory or from a Confluence page last updated six months ago.

The workflow is three steps. Boot the Spring Boot application locally at http://localhost:8080. Open Postman, select Import, and provide http://localhost:8080/v3/api-docs. Postman parses the live OpenAPI spec and generates a structured collection that exactly matches the current code state.

When a data model changes in the Java source, Postman's Update Collection re-syncs against the new spec automatically. No human transcription. No stale payloads.

Step 3: The Local Feedback Loop

The workflow only holds if it becomes the standard operating loop before any push. The pattern is simple. Write the code. Run REST Assured locally from the IDE, which takes around five seconds. If the test fails, stay on the machine, open Postman to visually inspect the response against the live local server, fix the underlying code, and re-run. If the test passes, push the PR with confidence.

The pipeline never sees the broken state. That is the point.

Anatomy of a Catch: The Pagination Index Bug

This is a real scenario that slips past traditional code review more often than it should.

The API is designed with a 1-based pagination index. page=1 returns the first page of results. During a refactor, a developer accidentally shifts the implementation to 0-based. The code compiles. The database queries run. The application starts cleanly. Nothing in the build output signals a problem. In a siloed workflow, this ships, and downstream clients break on deploy.

Here is how the dual-layer workflow catches it before that happens.

Phase 1: The Automated Gate Stops the Push

The REST Assured contract test for pagination is already in the suite:

@Test
public void verifyPaginationContract() {
    RestAssured.given()
        .queryParam("page", 1)
        .queryParam("size", 10)
    .when()
        .get("/api/v1/users")
    .then()
        .statusCode(200)
        .body("currentPage", org.hamcrest.Matchers.equalTo(1))
        .body("users.size()", org.hamcrest.Matchers.greaterThan(0));
}

The developer runs this locally. Because the code now treats page=1 as the second page, the API returns an empty list and currentPage: 2. The assertion fails in under five seconds. The branch stays local. The PR does not open.

Phase 2: Postman Makes the Bug Visible

The developer imports the current /v3/api-docs into Postman, fires a manual request with page=1, and reads the raw response:

{
  "currentPage": 2,
  "totalPages": 5,
  "users": []
}

The defect is immediately visible. No stack trace reading. No guesswork. Passing page=1 yields currentPage: 2. The index shift is confirmed.

The Resolution Decision

At this point the developer makes an explicit, documented decision rather than a silent one.

If it was an accidental bug, fix the index mapping back to 1-based in the controller, re-run the REST Assured test until it is green, and push clean code. The pipeline never sees the regression.

If it was an intentional requirement change, update the REST Assured assertion to equalTo(0), refresh the Postman collection to align, and commit the code and test change together in the same PR. The change is visible, traceable, and reviewed.

The critical difference from the broken workflow is that the decision cannot happen silently. It is forced into the open at the developer's desk, not discovered in production.

What This Gives You

REST Assured becomes an objective, automated gate. It does not care about developer intent. It verifies the contract and reports pass or fail.

Postman stays a flexible, interactive debugging surface. It is no longer a documentation artifact that drifts. It is a live mirror of the running code.

Both tools operate from the same definitions, derived in real time from the active application. There is no synchronization step to forget, and there is no version of the spec living outside the codebase.

What Comes Next

This loop works cleanly on a single developer's machine. The feedback is fast, the gate is reliable, and the contract is grounded in the actual code.

But what happens when 50 developers are all pushing to the same repository? What stops one of them from simply updating the REST Assured assertion to match their bug and pushing a green build?

That is the governance problem. That is exactly what Part 2 covers.

Part 2: Who Approved This Change? Managing API Contracts and Test Rot in Large Engineering Teams

The Zero-Drift API Series

Intro: The Zero-Drift API Series: Stop Trusting a Green Build You Can't Explain
Part 1: A Guide to Stop Breaking Merges: Unifying Postman and REST Assured in Spring Boot
Part 2: Who Approved This Change? Managing API Contracts and Test Rot in Large Engineering Teams
Part 3: The AI Superpower: How Vibe Coders Use OpenAPI as a Semantic Anchor
Part 4: Locking Down the Pipeline: Enforcing Contract Integrity Against Autonomous AI Agents

The Zero-Drift API Series: Stop Trusting a Green Build You Can't Explain

Prasad MK — Sat, 30 May 2026 17:20:26 +0000

The Zero-Drift API Series

Stop Trusting a Green Build You Can't Explain (Introduction)

There is a specific kind of production incident that hurts more than the others.

Not the kind where the stack trace is obvious. The kind where the build was green, the tests passed, and the code review looked clean, and yet something that used to work silently stopped working for a downstream team, a frontend client, or a mobile app. No alarm. No contract violation flagged. Just a broken assumption that traveled all the way to production dressed as a passing test.

That is the drift problem. And it is not a testing problem. It is a governance problem.

This four-part series is a practical engineering framework for teams running Spring Boot REST APIs who want deterministic confidence, not just green builds, across every layer of their delivery pipeline: from a solo developer's local machine, up through a large distributed team, through AI-assisted development, and all the way to autonomous AI agents writing and merging code.

What We Are Solving

The root cause is structural, not cultural. When Postman lives in one silo and REST Assured lives in another, teams get two independent descriptions of the same API that drift apart over time. The automated tests stop reflecting reality. The manual tests stop reflecting the code. And the first person to notice is usually a downstream consumer, in production.

Layered on top of that: anyone can rewrite a failing test to make it pass. A pagination index shifts from 1-based to 0-based, the assertion gets quietly updated to match, CI goes green, and three downstream clients break on the next deploy. The test did not catch the regression. The test became the regression.

Scale that to 50+ developers, add AI code generation tools that hallucinate payload keys and rewrite tests to cover their own mistakes, then add autonomous AI agents triggering pull requests, and the problem compounds fast.

The Four-Part Framework

Part 1: A Guide to Stop Breaking Merges: Unifying Postman and REST Assured in Spring Boot
The foundation. Establishing the Spring Boot application itself as the single source of truth via its live OpenAPI spec, so Postman and REST Assured consume identical definitions, eliminating drift at the individual developer loop before a line of code reaches the pipeline.

Part 2: Who Approved This Change? Managing API Contracts and Test Rot in Large Engineering Teams
The governance layer. What happens when 50+ developers are all touching the same codebase and one intentional change silently redefines a contract for everyone else. API versioning, CODEOWNERS, and the architectural choice between "never touch old tests" (which causes test rot) and "freely modify tests" (which kills downstream trust).

Part 3: The AI Superpower: How Vibe Coders Use OpenAPI as a Semantic Anchor
The AI-assisted development layer. How developers using Cursor, Copilot, or LLMs can ground their AI tools in the live local spec, eliminating hallucinated payload keys, automating test generation, and closing the feedback loop when AI-generated code silently breaks a contract.

Part 4: Locking Down the Pipeline: Enforcing Contract Integrity Against Autonomous AI Agents
The enforcement layer. When AI agents are autonomously writing code and opening PRs, you cannot rely on them remembering rules. Pre-commit hooks, .ai-rules.json constraint files, and a Coder/Auditor multi-agent pattern that treats the AI like an untrusted contributor, with deterministic, programmatic rails.

Each part builds on the last. You can apply Part 1 today, in isolation. Parts 2 through 4 progressively harden that foundation for teams at scale.

The goal throughout is the same: the build should be green because the contract is intact, not because someone updated the assertion.

Let's start local.

Part 1 -> A Guide to Stop Breaking Merges: Unifying Postman and REST Assured in Spring Boot

The Zero-Drift API Series

Rescuing a Broken Master from a Tag, Cleanly Through a PR

Prasad MK — Fri, 29 May 2026 06:46:14 +0000

It happens on real teams. Someone merges the wrong thing, a dependency update silently breaks the build, or a hotfix lands without a proper review. Whatever the reason, master is broken and you still have work to ship.

The good news: if you have a working release tag, you have everything you need. This guide walks through the full recovery arc, branching from the tag, adding new code on top, and raising a clean pull request that merges back to master with no surprise conflicts.

Why branching from the tag is the right move

The instinct is often to "fix master directly." Resist it. You do not know the full extent of what broke, and working on master violates the PR policy anyway. The tag is a precise snapshot of code that worked. Treating it as your new baseline keeps every subsequent decision clean and reviewable.

The strategy has three phases: establish a branch at the good commit, build your new work on top of it, then reconcile the divergence before raising a PR so the reviewer sees nothing but your intentional changes.

Phase 1: Create a branch from the tag

This single command is the foundation of everything that follows. It tells Git to set your new branch's starting commit to exactly where v1.3 points, not to the current tip of master.

# Create the branch rooted at the v1.3 tag
git checkout -b fix/restore-from-v1.3 v1.3

# Push it to Bitbucket so the team can see it
git push -u origin fix/restore-from-v1.3

Before writing a single line of new code, take a moment to understand exactly what diverged. This pays off when you reconcile later.

# What commits exist on master that are not in v1.3?
git log v1.3..origin/master --oneline

# What do those changes actually look like?
git diff v1.3 origin/master

Key insight: The diff above tells you exactly which files the broken commits touched. Those are the files you will need to consciously handle when you reconcile later. Keep a mental note of them.

Phase 2: Add your new work on top

You are now on a stable foundation. Build your features or fixes as normal, with one discipline: commit small and commit often. This is not just good practice in general, it becomes essential when you need to explain your PR to a reviewer who is looking at a branch that diverges from a broken master.

# Work on your files normally
git add src/feature-x.js src/utils.js

# Write commit messages that will read well in the PR
git commit -m "feat: add validation layer for incoming payloads"

git add tests/feature-x.test.js
git commit -m "test: unit coverage for payload validator"

# Push regularly : this keeps Bitbucket in sync
git push origin fix/restore-from-v1.3

Phase 3: Reconcile before you raise the PR

This is the step most guides skip or handle lazily. If you raise a PR now, Bitbucket will show conflicts because your branch started at v1.3 and master has moved (to broken commits) since then. The reviewer gets a noisy, confusing diff.

The correct approach is to resolve all of this locally on your branch before the PR goes up. Bitbucket then shows a clean diff of exactly what you intended to change.

Step 1: Pull master's current state into your branch

# Make sure you have the latest remote state
git fetch origin

# While ON your fix branch, merge master in
git checkout fix/restore-from-v1.3
git merge origin/master

Step 2: Resolve conflicts, keeping your code

Git will flag every file where your branch and the broken master diverge. For each conflict, you decide: keep your code, keep master's code, or blend them. In a recovery scenario, you almost always want to keep your branch's version.

# Option A: Accept your branch's version for a specific file
git checkout --ours src/api/handler.js
git add src/api/handler.js

# Option B: Open the file manually, remove conflict markers,
# edit to the state you want, then stage it
# <<<<<<< HEAD  (your branch)
# =======       (divider)
# >>>>>>> origin/master  (master)
git add src/api/handler.js

# Once all conflicts are resolved, commit the merge
git commit -m "merge: absorb origin/master, keep v1.3 baseline + new features"

# Push the resolved branch
git push origin fix/restore-from-v1.3

Watch out with --ours: During a git merge, "ours" refers to the branch you were on when you ran the merge your fix branch. "Theirs" refers to the branch being merged in master. This is the opposite of how it works during a git rebase. Keep this straight.

Step 3: Verify the diff before raising the PR

This is your sanity check. The three-dot diff shows only the commits that exist on your branch but not on master, exactly what the reviewer will see in the PR.

# Three-dot diff: "what does my branch add beyond master?"
git diff origin/master...fix/restore-from-v1.3

# Cross-check: should show ONLY your new intentional changes
git diff v1.3 HEAD

# If the output matches your intentions, you are ready to raise the PR

Raising the pull request in Bitbucket

With the branch pushed and conflicts pre-resolved, the PR creation is straightforward. In Bitbucket, navigate to your repository, go to Pull Requests, and create a new PR from fix/restore-from-v1.3 to master.

Source branch: fix/restore-from-v1.3. Target branch: master. Bitbucket should now show no merge conflicts because you resolved them on your branch.
Write a clear PR description. Mention that the branch was rooted at tag v1.3 due to the broken master state. Reviewers need this context to evaluate the diff correctly.
Link the relevant issue or Jira ticket if your team uses one. This anchors the PR to business context and keeps the audit trail intact.
The reviewer sees a clean, intentional diff. No broken master code, no spurious conflict markers. Just your new work on top of the last stable release.

What happens to master after the merge

When the PR merges, master will contain: the complete history up to v1.3, the merge commit that absorbed the broken state, and your new feature commits on top. The broken commits are still in the history, they are not erased, but they are effectively neutralized because your branch's code takes precedence in the final snapshot.

This is the cleanest outcome achievable under a PR-only policy. You did not force-push, you did not rewrite shared history, and every change that landed in master went through a review.

A note on force-pushing master: Some guides suggest resetting master to the tag and force-pushing. That works in a solo repo but is destructive on a shared branch, it rewrites history that other developers may have already pulled. The approach in this guide avoids that entirely.

Quick reference: the full command sequence

# 1. Branch from the working tag
git checkout -b fix/restore-from-v1.3 v1.3
git push -u origin fix/restore-from-v1.3

# 2. Understand the divergence (read-only, safe to run anytime)
git log v1.3..origin/master --oneline
git diff v1.3 origin/master

# 3. Do your work, commit often
git add <files>
git commit -m "feat: your message here"
git push origin fix/restore-from-v1.3

# 4. Absorb master into your branch (pre-resolve before PR)
git fetch origin
git merge origin/master
# resolve conflicts, then:
git add .
git commit -m "merge: absorb master, keep v1.3 baseline + new features"
git push origin fix/restore-from-v1.3

# 5. Verify the diff is clean
git diff origin/master...fix/restore-from-v1.3

# 6. Raise the PR in Bitbucket: fix/restore-from-v1.3 -> master

The principle worth keeping

Tags are not just release markers. They are named, immutable recovery points. Any time master becomes unstable and a working tag exists, you have a clean path back, without rewriting shared history, without bypassing your PR policy, and without making your reviewer's job harder than it needs to be. The work is in the reconciliation step. Get that right, and the merge is uneventful.