API Backward Compatibility Guard
This loop ensures that modifications to your API specifications maintain backward compatibility with existing consumers. It uses oasdiff to detect breaking changes between old and new OpenAPI specs, iterating until all breaking changes are resolved or the maximum iteration limit is reached.
Goal
Ensure API changes do not break consumers
How to Run
Run this loop in your terminal using a prompt-based agent to detect and resolve API backward compatibility issues.
- 01
Prepare OpenAPI Spec Files
Ensure you have two OpenAPI specification files: old.yaml (current version) and new.yaml (proposed version).
- 02
Execute Loop
Run the loop command in your agent interface (e.g., Cursor, Claude Code). The agent will execute the oasdiff check and iterate based on results.
- 03
Resolve Breaking Changes
If breaking changes are found, manually update new.yaml to address compatibility issues. Re-run the loop until no breaking changes remain.
Workflow Steps
- 01
Run oasdiff breaking old.yaml new.yaml to detect breaking changes
If no breaking changes detected, exit loop successfully
- 02
Parse oasdiff output to identify specific breaking change details
If changes are detected, proceed to next step
- 03
Present breaking change details to user for manual resolution
Wait for user to update new.yaml with compatibility fixes
- 04
Return to Step 1 and repeat until exit condition is met or max iterations reached
If max iterations reached without success, report unresolved breaking changes
Kickoff Prompt
Start the "API Backward Compatibility Guard" loop. Goal: Ensure API changes do not break consumers Max iterations: 10 Between iterations run: oasdiff breaking old.yaml new.yaml Exit when: No breaking changes detected You are an API compatibility guard. Your task is to check for breaking changes between old.yaml and new.yaml using oasdiff. If breaking changes are found, inform the user about each issue and ask them to update new.yaml to restore compatibility. Repeat this process until no breaking changes exist or you've made 10 attempts. Self-pace this loop. After each iteration, run `oasdiff breaking old.yaml new.yaml` and evaluate the output, and only continue if the exit condition is not met (No breaking changes detected). Stop when the exit condition passes or 10 iterations are reached. Give a short status update each pass.
Guardrails
hardcoded- ·Never modify the check command or exit condition
- ·Ensure both old.yaml and new.yaml exist and are valid OpenAPI specs before running oasdiff
- ·Do not attempt to auto-fix specs; human intervention is required for resolving breaking changes
- ·Stop iterations immediately if oasdiff encounters an error or cannot parse the specs
Flow Diagram
Related loops — API
API
Resolve API Error Responses
This loop standardizes API error responses across the application to improve client-side error handling and debugging. It ensures all error responses follow a consistent structure (e.g., RFC 7807 Problem Details format) with appropriate HTTP status codes and machine-readable error codes.
API
Fix Failing Integration Endpoints
Automatically detects and resolves issues in failing API integration endpoints through iterative testing and code modifications.
API
API Performance Budget
A coding loop focused on optimizing API performance to ensure P95 latency stays under a defined target threshold. This loop iteratively runs load tests, analyzes bottlenecks, and implements optimizations until the goal is achieved or maximum iterations are reached.