API Contract Checker for Continuous Integration

The problem with silent API breakage

A backend developer renames a field, makes a response property nullable, or adds a required query parameter. Tests pass, because the tests were updated in the same pull request. The web client, the mobile app and the partner integration find out in production. For mobile teams it is worse: old app versions stay on phones for months, so a breaking change keeps breaking people long after it is fixed on the server.

Versioning is supposed to prevent this and it does not, because nothing checks that the version was actually bumped when the contract changed. API breakage is a communication failure with a technical shape, and it can be caught mechanically.

What already exists and the gap

• oasdiff is an open source CLI and GitHub Action that diffs two OpenAPI specs and reports breaking changes with a large, detailed rule set.
• Optic was the popular open source option for years; its repository was archived in January 2026, which pushed many teams to look for alternatives.
• Azure openapi-diff is Microsoft's command line tool for breaking change detection between two specs, built for their own API review process.
• Bump.sh and Stoplight are hosted API documentation and design platforms that include change tracking as part of a paid product.

Rule based diffing is solved well. What these tools mostly leave to the team is the policy around it: whether this breaking change came with a version bump, how the contract of one endpoint has drifted over a year, and whether the classification rules are actually right. Your contribution is a smaller, well evaluated checker with a version policy, a history view, and published accuracy numbers against real API histories.

What you build

Three pieces:

• The engine: loads two specs, resolves references, walks paths, operations, parameters, request bodies and response schemas, and emits a list of typed differences.
• The CI integration: a GitHub Action that checks out the base branch, extracts both specs, runs the engine, applies the repository policy and posts a comment grouped by endpoint.
• The history service: stores each merged contract so a small dashboard can show an endpoint timeline.

Users are backend developers (who read the pull request comment), tech leads (who set policy) and client developers (who read the history when something changed).

The technically interesting part

Classification is the whole project. Adding an optional response field is safe. Adding a required request parameter is breaking. Making a response field nullable breaks clients that assumed it was not, while making a request field nullable does not. Widening an enum is safe in a request and potentially breaking in a response. The direction of data flow flips the rule, and JSON Schema composition (allOf, oneOf) makes the comparison a tree problem, not a line diff.

Show your supervisor a rules table with the reasoning for each rule, the test that covers it, and a clear statement of which way you lean when unsure. False positives kill adoption: a checker that cries breaking change over a reordered enum is switched off within a week, so conservative in the right direction matters more than catching everything.

How to evaluate it

• Accuracy on real history: pick three open source APIs that publish OpenAPI specs and changelogs. Replay a year of releases and compare flagged breaking changes against those the project documented. Report precision and recall, and write up every miss and every invented break.
• Comparison with oasdiff: run both on the same release pairs and explain the disagreements.
• Speed: time the Action end to end; target under 30 seconds for a 100 endpoint spec.
• Usability: ask five developers to read three pull request comments and say what broke; record correct answers.

Suggested plan

1. Weeks 1 to 2: collect ten real breaking changes from public changelogs and write them as failing tests.
2. Weeks 3 to 6: spec loading, reference resolution, and the comparison engine for paths, parameters and schemas.
3. Weeks 7 to 8: version policy, policy file and the GitHub Action with pull request comments.
4. Weeks 9 to 10: history storage and the dashboard.
5. Weeks 11 to 14: replay evaluation on three APIs, comparison with oasdiff, write up.

Path to a product

The realistic path is open source adoption first: a well documented Action that small teams can add in five minutes. Your first users are teams you know, for example a startup with a mobile app whose old versions cannot be forced to update. A hosted version with the history dashboard, approval workflow and Slack alerts could charge per repository, the same model other API tooling uses. Even without revenue, a tool with real users and a published evaluation is a strong portfolio centrepiece for backend and platform roles.

Scope warning

Do not build an API gateway, a mock server or a documentation site. Do not write your own YAML parser or try to support Swagger 2.0 and every OpenAPI edge case; state what you support. GraphQL is a stretch goal, not a second project.

Learn what you need on Sefism

• Backend roadmap : HTTP APIs, versioning and testing in the order you need them.
• DevOps and cloud cheat sheet : CI pipelines and GitHub Actions basics for the integration.
• OpenAPI Specification : the format your engine walks; read the schema and reference sections closely.
• JSON Schema : where most of the tricky classification rules live.
• API Design roadmap : versioning and compatibility practices to justify your rules.

Get help with this idea

This is a good project if you keep it narrow and let real changelogs drive your rules. Tauseef can help you choose which APIs to replay, decide which change classes to support first, and shape an evaluation examiners will trust. If you are new here, create a free account first.

• Discuss this idea with a mentor
• Send a query to Tauseef
• Book a 1:1 session