Using API Evolution Tracking
Step-by-step guide to tracking API changes with baselines: set a versioning strategy, create baselines, compare changes, review classifications, create new versions when needed, and publish changelogs for consumer teams.
This guide walks through the complete API evolution workflow: from setting a versioning strategy on your API, through baseline creation and comparison, to publishing changelogs that consumer teams can browse without repository access.
Step 1: Set a Versioning Strategy
Each API can have its own versioning strategy. This determines how version labels are formatted and how the system recommends version bumps.
Step 2: Create Your First Baseline
A baseline captures the architectural state at a governance-approved moment. For API evolution, it serves as the "before" snapshot that changes are compared against.
Step 3: Make Changes to Your APIs
After creating a baseline, continue working on your APIs as normal. Add endpoints, modify schemas, deprecate operations, update descriptions. Auto-save handles everything - there is no need to track individual changes manually.
Step 4: Review Classified Changes
When you are ready to review what has changed since the baseline, open the API Evolution report.
Step 5: Handle Breaking Changes
If the comparison reveals breaking changes and a major version bump is recommended, you have two options: fix the breaking changes, or create a new API version.
Step 6: Create a New Baseline and Changelog
After resolving or versioning your changes, create a new baseline to capture the current state. The system generates a changelog recording every change between the two baselines.
Step 7: Publish Changelogs
When you publish your documentation site, changelogs are included automatically. Consumer teams can browse them without needing repository access.
Change Classification Reference
The system classifies every change into one of four categories based on its impact on consumers:
| Category | Trigger | Version Impact |
|---|---|---|
| Breaking | Removing a resource, changing a structural property, removing security | Major bump |
| Deprecation | Marking a resource as deprecated | Minor bump |
| Additive | Adding a new resource | Minor bump |
| Cosmetic | Changing descriptions, tags, or notes | Patch bump |
Track how your APIs change over time with baseline-driven comparison, structured change classification, version recommendations, and published changelogs. Covers all API types: REST, GraphQL, gRPC, AsyncAPI, Webhooks, and MCP.
Step-by-step guide to creating governance baselines, verifying integrity, comparing drift, and integrating baselines into your architecture review workflow.
Everything in NeoArc Studio is a file. Your diagrams, documents, and schemas live in Git alongside your code, with full version history and standard collaboration workflows.