API evolution tracking is baseline-driven. Create named snapshots at meaningful points (after an API review, before a release), then compare against them to see exactly what changed, classified by impact severity. The system covers all API types and produces published changelogs that consumer teams can browse without needing access to the repository.
How It Works
Baseline Your Contracts
Create named snapshots at meaningful points: after an API review, before a release, when a contract is approved. Each baseline pins a Git commit SHA for exact reproducibility.
Work Freely
Auto-save handles everything. No noise from in-progress work, no need to track individual changes manually. The baseline captures the before-state so you can focus on design.
Compare When Ready
Select a baseline and see exactly what changed. Each change is classified as breaking, additive, deprecation, or cosmetic. The system recommends a version bump based on severity.
Create New Versions with Confidence
When breaking changes are needed, the system guides you through creating a new API version directory with auto-generated migration task suggestions.
Change Classification
Every change is classified into one of several categories based on its impact on consumers:
| Category | When It Applies | Version Impact | Example |
|---|
| Breaking | Removing a resource, changing a structural property, removing security | Major bump | Deleting a REST endpoint, changing a gRPC method's request schema, removing an MCP tool |
| Deprecation | Marking a resource as deprecated | Minor bump | Setting deprecated: true on an AsyncAPI operation |
| Additive | Adding a new resource | Minor bump | Adding a new webhook event, a new GraphQL query, a new MCP prompt |
| Cosmetic | Changing descriptions, tags, or notes | Patch bump | Updating an endpoint's description or adding tags |
Version Management
Structured Versioning
Choose from semantic (1.2.3), major-minor (1.2), simple major (v2), date-based (2024.03.06), or custom formats. Set the strategy once per API and the system follows it.
Automatic Recommendations
The system analyses all changes and recommends the next version. Breaking changes suggest a major bump, new additions suggest minor, cosmetic-only changes suggest patch.
Version-and-Migrate Workflow
When a major version is needed, the system creates a new versioned directory with copied API files and generates migration task suggestions for each breaking change.
Multi-Version Coexistence
Both old and new versions live in the workspace simultaneously. Impact analysis shows downstream effects on both versions. Lineage traces through shared model entities.
Supported API Types
API evolution tracking works identically across all API types. Each type has its own parser and structural property definitions:
REST
Endpoints, methods, paths, request/response schemas, security schemes, parameters.
GraphQL
Operations, arguments, return types, auth requirements, deprecation.
gRPC
Services, methods, streaming flags, request/response schemas, retry policies, HTTP transcoding.
AsyncAPI
Channels, operations, messages, payload schemas, protocol bindings, correlation IDs.
Webhooks
Events, payload schemas, headers, delivery overrides, security overrides.
MCP
Tools, resources, prompts, input/output schemas, annotations, template parameters.
Published Changelogs
Changelog Viewer
Each changelog shows version badges, category summary pills, and changes grouped by resource type with colour-coded category indicators and expandable property details.
Version History Timeline
A dedicated page lists all version transitions in reverse chronological order. Each entry shows the version range, date, and summary counts with click-to-navigate.
Drift Dashboard Integration
The drift dashboard in the source control panel shows API contract drift alongside general architectural drift. Select a baseline and immediately see:
Drift Percentage
Overall architectural drift from the baseline with severity indicators (low, medium, high, critical).
API Contract Drift
A stacked category breakdown bar showing the proportion of breaking, deprecation, additive, and cosmetic changes across all API types.
Version Recommendation
Based on the worst-case change category, the system recommends a major, minor, or patch version bump.
Source Control Native
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.
API Documentation
Document REST APIs with full endpoint specifications, OpenAPI import and export, seven HTTP methods, parameters, request and response bodies linked to shared schemas, authentication schemes, and a published API browser. REST is part of the API documentation suite (REST, GraphQL, gRPC, AsyncAPI, Webhooks, MCP) sharing a unified schema layer.
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.
