Rust API evolution and contract verifier
A Rust command-line verifier that compares OpenAPI contracts, identifies affected named consumers, and records reproducible evidence for breaking and compatible changes.
Project definition
Problem statement
A changed API may remain syntactically valid while breaking an existing consumer through a removed field, stricter validation, altered error response, renamed enum value, or different authentication requirement.
The engineering problem is to compare meaning rather than text alone, account for request and response direction, connect a change to actual consumer expectations, and produce a repeatable compatibility decision with evidence.
Project objectives
- Parse and normalise local OpenAPI 3.1 and 3.2 JSON or YAML specifications.
- Classify request, response, schema, operation, security, and status-code changes.
- Connect changed contract paths to recorded named consumer expectations.
- Recommend semantic version changes from the observed finding severity.
- Measure classification accuracy, consumer impact detection, and analysis performance.
Project structure
Project components
Specification loader
Loads bounded JSON or YAML documents, accepts local references only, rejects symlinks, and enforces nesting and recursion limits.
Semantic difference engine
Finds operation, parameter, schema, response, enum, constraint, and security changes with direction-aware rules.
Consumer evidence matcher
Matches recorded request and response expectations to changed operations, fields, statuses, and media types.
Version recommender
Converts the highest observed severity into an expected semantic version change and checks the proposed candidate version.
Evidence reporter
Writes findings, input hashes, consumer impact, version advice, runtime, and scope notes to five reviewable formats.
Experiment runner
Executes fifteen labelled cases, calculates classification metrics, compares an external tool, and measures scaling.
Methodology
Project workflow
- 01Load API versions
The baseline and candidate specifications are parsed under explicit file, depth, and reference boundaries.
- 02Calculate semantic changes
Direction-aware rules classify every supported contract difference.
- 03Identify consumers
Recorded expectations are matched to changed operations, fields, responses, media types, and statuses.
- 04Check the version
The highest finding severity determines the recommended release increment and validates the proposed version.
- 05Write the evidence
The verifier stores hashes, findings, consumer impact, recommendation, runtime, and limitations in reviewable reports.
Demonstration scenario
A baseline student-record API is compared with a candidate release. The candidate makes an optional request field mandatory. The verifier records an error finding, identifies the two named consumers that submit requests without that field, recommends a major version change, and writes the complete evidence report.
Engineering
Tools and method
- Analysis core
- Rust enums and typed structures represent operations, schemas, findings, severity, consumer evidence, and version decisions.
- Specification support
- OpenAPI 3.1 and 3.2 JSON or YAML input with local references, cycle protection, validation errors, and bounded processing.
- Consumer model
- A bounded JSON evidence file records named consumers, versions, and request or response expectations without personal information.
- Report layer
- Deterministic serializers produce JSON, CSV, Markdown, escaped HTML, and an aggregate responsive dashboard.
- Experiment fixtures
- Fifteen versioned API pairs encode ten breaking and five compatible changes with independent ground truth.
- Reproducibility
- Pinned Rust and Python dependencies, input hashes, automated tests, and retained experiment outputs support review.
Testing
Evaluation
Evaluation measures
- Ten true positives, five true negatives, zero false positives, and zero false negatives on the prepared corpus
- Prepared-corpus precision, recall, and specificity of 1.0
- Seven labelled cases connected to affected named consumers
- Correct semantic version recommendation on every labelled case
- Median and P95 runtime measured from 10 to 1,000 operations
- Comparison with oasdiff 1.29.1 and an explicit explanation of the one policy difference
- Twenty-five automated Rust tests plus repository, document, dependency, and security checks
Project boundaries
- The verifier supports documented OpenAPI 3.1 and 3.2 HTTP contract patterns and does not implement every extension or vendor-specific rule.
- All specification references must be local. Network references and symlinked inputs are rejected.
- A compatible result covers the analysed specification and fixtures, not every possible undocumented consumer behaviour.
- The consumer evidence is synthetic and contains no personal, buyer, account, or production information.
Included
- 01Rust command-line contract verification engine
- 02Fifteen labelled API evolution cases with named consumer evidence
- 03JSON, CSV, Markdown, HTML, and dashboard reports
- 04Classification, consumer-impact, version, and scaling results
- 05Complete source code in a private GitHub repository
- 06Complete 95-page project documentation in PDF and editable Word formats
- 07Complete 13-page setup and usage guide in PDF and editable Word formats
Project record
No information is collected on this page.
- Permanent project ID
- GP-CS-0MHQ7PB
- Catalogued
- 21 Aug 2026
- Completed
- 24 Aug 2026
- Verified
- 24 Aug 2026
- Demonstration
- Included in repository
Handover
After purchase
- 01Payment is confirmed
The project is marked unavailable and cannot be purchased again.
- 02Repository access is granted
The buyer's submitted GitHub account receives access to the private repository.
- 03The purchase record is delivered
The certification sheet is prepared from the reviewed buyer details and sent privately by email.