ContractSync: Bringing Backend and Frontend Developers onto the Same API Contract
One API contract. Two specialized agents. Less synchronization chaos.
The Problem: API Changes Can Break More Than One Team
In software development, backend and frontend teams often work in parallel. This improves productivity, but it also creates a common problem: API contract drift.
Imagine a backend developer renames a response field from
spot_status to availability_state . The backend code may work perfectly, but the frontend could still be expecting the old field.The result can be outdated TypeScript interfaces, incorrect mock data, unexpected integration errors and wasted debugging time.
The challenge is not simply identifying that an API changed. It is coordinating the change across the entire development workflow without breaking existing consumers.
That is the problem we set out to address with ContractSync.
Introducing ContractSync
ContractSync is an AI-powered API contract coordination workflow designed to help backend and frontend development stay synchronized.
The idea is to divide the work between two specialized engineering agents, with a human developer retaining control over important decisions.
The system has two primary agent roles:
1. SpecArchitect — Backend API Guardian
SpecArchitect is responsible for understanding and reviewing API contract changes.
Its responsibilities include:
- Analyzing OpenAPI specifications.
- Identifying potentially breaking changes.
- Highlighting compatibility risks.
- Suggesting backward-compatible migration strategies.
2. FrontendSync — Frontend Integration Engineer
FrontendSync focuses on the frontend impact of approved API changes.
Its responsibilities include:
- Updating TypeScript interfaces.
- Synchronizing mock data.
- Keeping frontend definitions aligned with the API specification.
- Running TypeScript validation to identify integration issues.
A human approval step sits between analysis and implementation. This prevents an agent from making potentially disruptive API changes without developer review.
A Practical Example
Consider an API endpoint:
GET /api/spots Its original response looks like this:
{ "id": 101, "name": "Library", "spot_status": "available"}Now imagine the backend team wants to rename
spot_status to availability_state and introduce a new role field.A direct rename could break existing frontend consumers.
ContractSync approaches the change as a coordinated migration:
- Analyze: SpecArchitect examines the proposed API change and identifies the compatibility risk.
- Recommend: It proposes retaining the old field as optional and deprecated while introducing the new field.
- Approve: A human developer reviews and approves the migration.
- Synchronize: The approved specification is reflected in TypeScript interfaces and mock data.
- Validate: The TypeScript compiler checks the updated frontend code.
The goal is to make API changes deliberate, traceable and safer for the teams consuming them.
Why Specialized Agents?
A single general-purpose agent can perform several development tasks, but separating responsibilities creates a clearer workflow.
SpecArchitect focuses on API correctness and compatibility. FrontendSync focuses on frontend consistency and validation.
This division makes responsibilities easier to understand and creates a natural handoff point for human review.
It also demonstrates how AI agents can be used as collaborators in an engineering process rather than simply as code-generation tools.
Connecting the Workflow with Switch
The original vision for ContractSync was to use Switch as the collaboration layer connecting specialized agents and human developers through a shared communication environment.
The intended workflow uses a shared room such as
#api-contract-room , where agents can exchange updates and a developer can review proposed changes.During development, we tested the agent workflow using Google's Antigravity CLI and its Agent Client Protocol (ACP). We also configured a local Mattermost environment while exploring the Switch integration.
However, we encountered a significant compatibility limitation: the Switch Console version we tested reported that its Antigravity ACP provider was unsupported on Windows.
As a result, we validated the agent workflow directly through Antigravity, but did not complete or verify the official Switch-mediated agent-to-Mattermost communication.
The public demonstration therefore includes a local workflow simulator. It should not be mistaken for a fully live Switch-connected collaboration system.
Technical Implementation
The project brings together several technologies:
- TypeScript: Core application and agent workflow implementation.
- OpenAPI: API contract representation and change analysis.
- Google Antigravity CLI: Direct agent workflow testing through ACP.
- Mattermost: Local messaging environment configured during integration work.
- TypeScript Compiler: Validation of synchronized frontend definitions.
- GitHub Pages: Hosting the interactive public demonstration.
The automated test suite reports 11 passing checks. These include a simulated Switch protocol test and a direct Antigravity ACP workflow test; they do not establish that the official Switch integration is working.
What We Learned
Building ContractSync highlighted several practical lessons:
1. Compatibility matters as much as functionality.
An API change that works for the backend can still break existing frontend consumers. Backward compatibility needs to be part of the development process.
2. Human approval is valuable.
Autonomous agents should not automatically make every consequential engineering decision. A clear approval step can reduce the risk of unintended changes.
3. Agent orchestration is more than running multiple agents.
A useful multi-agent workflow needs clear responsibilities, shared context, reliable handoffs and validation.
4. Integration claims must be verified.
A simulator can demonstrate a workflow, but it cannot prove that a real external platform integration works. Testing the actual communication path is essential.
What's Next?
The next development priorities for ContractSync are:
- Complete and verify the official Switch connection on a supported environment.
- Enable real agent-to-agent communication through a shared collaboration room.
- Add support for more API change scenarios.
- Introduce automated contract-diff reporting.
- Expand validation to include additional frontend consumers and integration tests.
Try ContractSync
ContractSync explores a practical idea: what if backend and frontend teams had specialized AI engineering collaborators helping them stay aligned whenever an API changes?
The broader goal is not to replace developers. It is to reduce coordination overhead, catch compatibility issues earlier and make cross-team software development more reliable.
Built for the Flip the Switch Hackathon by WeMakeDevs, DevTools Academy and Switch.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article