API Versioning & Changelog Tools

Developer guide to API version management and automated changelog generation

This guide covers how to use Staqr's API versioning tools during development, testing, and release processes.

Overview

Staqr provides automated tooling for:

Changelog Generation: Compare API versions and generate release notes
Breaking Change Detection: Prevent accidental API breaking changes in PRs
AI-Enhanced Changelogs: Transform technical diffs into readable release notes

These tools integrate with your development workflow and CI/CD pipelines.

Tool 1: Changelog Generation Script

Purpose

Compare OpenAPI specifications between two git tags and generate a markdown changelog.

Location

scripts/generate-changelog.sh

Usage

./scripts/generate-changelog.sh <previous-version> <current-version>

Example

# Compare v1.0.0 to v1.1.0
./scripts/generate-changelog.sh v1.0.0 v1.1.0

# Output: docs-new/changelogs/CHANGELOG-v1.1.0.md

What It Does

Checks out previous version (e.g., v1.0.0)
Generates OpenAPI spec from that version's code
Checks out current version (e.g., v1.1.0)
Generates OpenAPI spec from current code
Compares specs using oasdiff
Generates markdown changelog with:
- Docusaurus frontmatter (title, description)
- New endpoints
- Modified endpoints
- Removed endpoints
- Breaking changes section (if any detected)
Saves to docs-new/changelogs/CHANGELOG-v1.1.0.md

Output Format

---
title: 'API Changelog v1.1.0'
description: 'API changes from v1.0.0 to v1.1.0'
sidebar_position: 1
---

# API Changelog: v1.1.0

**Release Date:** 2026-01-19
**Previous Version:** v1.0.0

---

## New Endpoints: 5

### POST /api/v1/flows/{flowId}/execute
- endpoint added
- request body: application/json (FlowExecutionRequest)
- response: 200 (FlowExecutionResponse)

### GET /api/v1/connections/{connectionId}/health
- endpoint added
...

## Breaking Changes

⚠️ Parameter `customerId` removed from POST /api/v1/orders
⚠️ Response format changed for GET /api/v1/billing/invoices

Prerequisites

Git tags exist for the versions you want to compare
OpenAPI spec can be generated for both versions
oasdiff installed (automatic via go install)

Troubleshooting

Error: "Tag v1.0.0 not found"

# Check available tags
git tag --list | grep "^v"

# Create tags if needed
git tag v1.0.0

Error: "Could not generate OpenAPI spec"

# Ensure the version can build
git checkout v1.0.0
cd packages/server/api
pnpm install
pnpm run build
pnpm run generate:openapi

Tool 2: AI-Enhanced Changelog Script

Purpose

Transform technical oasdiff output into human-friendly release notes using Claude AI.

Location

scripts/generate-ai-changelog.py

Usage

python3 scripts/generate-ai-changelog.py \
    <previous-spec.json> \
    <current-spec.json> \
    <version> \
    <output-file>

Example

# Generate AI-enhanced changelog for v1.1.0
python3 scripts/generate-ai-changelog.py \
    /tmp/openapi-v1.0.0.json \
    /tmp/openapi-v1.1.0.json \
    v1.1.0 \
    docs-new/changelogs/CHANGELOG-v1.1.0-ai.md

Prerequisites

Python 3.x installed

Anthropic package:

pip install -r requirements-changelog.txt
# or
pip install anthropic

Anthropic API key:

export ANTHROPIC_API_KEY=sk-ant-api03-...

What Makes It Different

Standard Changelog	AI-Enhanced Changelog
Technical endpoint diffs	Plain English explanations
Raw schema changes	Grouped by use case/domain
No context	Impact analysis and migration examples
For API developers	For all developers

Example Output

## Flow Management

### ✨ New: Execute Flows Programmatically

You can now trigger flows via the API, enabling scheduled jobs and external automation.

**Use Case:** Run a flow when an external event occurs

**Example:**
```typescript
import { StaqrClient } from '@staqr/api-client';

const client = new StaqrClient({ apiKey: process.env.STAQR_API_KEY });

const result = await client.flows.execute(flowId, {
  payload: { customerId: 'cust_123' }
});

console.log(result.executionId); // flow-run-abc123

Migration: No changes required for existing code (new feature only)

---

## Tool 3: Breaking Change Detection (PR Workflow)

### Purpose

Automatically detect API breaking changes when you create a pull request.

### Location

`.github/workflows/api-breaking-changes.yml`

### How It Works

```mermaid
graph TD
    A[Create PR] --> B{Modifies API code?}
    B -->|Yes| C[Generate Base Branch Spec]
    B -->|No| D[Workflow Skipped]
    C --> E[Generate PR Branch Spec]
    E --> F[Run oasdiff breaking]
    F --> G{Breaking Changes?}
    G -->|Yes| H[Comment on PR with Warning]
    G -->|No| I[Comment with Summary]

Triggers

The workflow runs when a PR modifies:

packages/server/api/src/**
packages/shared/src/**

PR Comments

If breaking changes detected:

## ⚠️ Breaking API Changes Detected

**This PR introduces breaking changes to the Staqr Platform API.**

<details>
<summary>Breaking Changes</summary>

- Parameter `customerId` removed from POST /api/v1/orders
- Response type changed for GET /api/v1/billing/invoices
- Endpoint DELETE /api/v1/legacy-endpoint removed

</details>

**Action Required:**
- If intentional: Bump major version (e.g., v1.x.x → v2.0.0)
- If unintentional: Revise changes to maintain backward compatibility

If no breaking changes:

## ✅ API Changes Detected (No Breaking Changes)

This PR modifies the API but does not introduce breaking changes.

<details>
<summary>API Changes</summary>

- New endpoint: POST /api/v1/flows/{flowId}/execute
- New parameter: GET /api/v1/connections?status=active

</details>

Testing Before PR

Check for breaking changes locally before creating a PR:

# 1. Generate current branch spec
cd packages/server/api
pnpm run generate:openapi
cp dist/openapi.json /tmp/pr-spec.json

# 2. Generate main branch spec
git stash
git checkout main
pnpm run build
pnpm run generate:openapi
cp dist/openapi.json /tmp/main-spec.json
git checkout -

# 3. Check for breaking changes
oasdiff breaking /tmp/main-spec.json /tmp/pr-spec.json

Tool 4: Automatic Release Changelogs

Purpose

Automatically generate and publish changelogs when you release a new version.

Location

.github/workflows/changelog-generation.yml

How It Works

Trigger: Push a version tag

git tag v1.2.0
git push origin v1.2.0

What Happens:

GitHub Actions detects the new tag
Finds the previous version tag automatically
Runs scripts/generate-changelog.sh
Commits changelog to docs-new/changelogs/
Pushes to nightly branch
(Optional) Runs AI enhancement if ANTHROPIC_API_KEY secret configured
Uploads changelog as GitHub artifact

Result: Changelog appears in Docusaurus automatically

Manual Trigger

You can also run the workflow manually for any two versions:

Go to Actions tab in GitHub
Select Generate API Changelog workflow
Click Run workflow
Enter previous version (e.g., v1.0.0)
Enter current version (e.g., v1.1.0)
Click Run

Development Workflow

During Development

While building new features:

# Preview what will be in the changelog
cd packages/server/api
pnpm run generate:openapi

# Compare against last release
oasdiff diff \
    /path/to/v1.0.0/openapi.json \
    dist/openapi.json \
    --format text

Before Creating PR

Check for unintentional breaking changes:

# Generate specs for both branches (see "Testing Before PR" above)
oasdiff breaking /tmp/main-spec.json /tmp/pr-spec.json

If breaking changes found:

Intentional? Plan to bump major version
Unintentional? Revise your changes to maintain compatibility

During Code Review

When reviewing a PR:

Check the automated comment from API Breaking Change Detection
Review the diff summary
If breaking changes present, verify they're intentional
Confirm major version will be bumped if merging

At Release Time

# 1. Decide on version number
# - Breaking changes? → Bump major (v2.0.0)
# - New features? → Bump minor (v1.1.0)
# - Bug fixes only? → Bump patch (v1.0.1)

# 2. Create and push tag
git tag v1.1.0
git push origin v1.1.0

# 3. Changelog auto-generates
# - Check GitHub Actions for progress
# - Changelog appears in docs within minutes

Configuration

GitHub Secrets (Optional AI Enhancement)

To enable AI-enhanced changelogs in GitHub Actions:

Go to repository Settings
Navigate to Secrets and variables → Actions
Click New repository secret
Name: ANTHROPIC_API_KEY
Value: Your Claude API key from Anthropic Console
Click Add secret

Without this secret: Standard technical changelogs still work (oasdiff only)

Local Setup

Install oasdiff:

go install github.com/oasdiff/oasdiff@latest

Install Python dependencies (for AI enhancement):

pip install -r requirements-changelog.txt

Set API key (for AI enhancement):

export ANTHROPIC_API_KEY=sk-ant-...
# Or add to ~/.bashrc or ~/.zshrc for persistence

Best Practices

1. Always Check for Breaking Changes

Before merging to main:

oasdiff breaking /tmp/main-spec.json /tmp/pr-spec.json

2. Document Breaking Changes

If introducing a breaking change intentionally:

Update the PR description with migration instructions
Add deprecation notices before removal
Coordinate with API consumers

3. Use Semantic Versioning

Change Type	Version Bump	Example
Add endpoint	Minor	v1.0.0 → v1.1.0
Add optional parameter	Minor	v1.0.0 → v1.1.0
Remove endpoint	Major	v1.0.0 → v2.0.0
Change response type	Major	v1.0.0 → v2.0.0
Bug fix	Patch	v1.0.0 → v1.0.1

4. Keep OpenAPI Specs Updated

Ensure your OpenAPI spec stays in sync with code:

# After API changes, regenerate spec
cd packages/server/api
pnpm run generate:openapi

# Verify spec is accurate
cat dist/openapi.json | jq '.paths | keys' | head -20

5. Test Changelog Generation Locally

Before pushing a version tag, test the changelog:

# Create test tags
git tag v0.99.0-test
git tag v1.0.0-test

# Generate changelog
./scripts/generate-changelog.sh v0.99.0-test v1.0.0-test

# Review output
cat docs-new/changelogs/CHANGELOG-v1.0.0-test.md

# Cleanup test tags
git tag -d v0.99.0-test v1.0.0-test
rm docs-new/changelogs/CHANGELOG-v1.0.0-test.md

Troubleshooting

"oasdiff: command not found"

# Install oasdiff
go install github.com/oasdiff/oasdiff@latest

# Add to PATH (if needed)
export PATH="$PATH:$HOME/go/bin"

# Verify
oasdiff --version

"Could not generate OpenAPI spec for v1.0.0"

The version must have a buildable API package:

# Check out the version
git checkout v1.0.0

# Try building
cd packages/server/api
pnpm install
pnpm run build

# Check if generate:openapi script exists
grep "generate:openapi" package.json

# If missing, spec may not exist for that version
# Use a later version or add the script

"Breaking changes in non-major version"

The script warns if breaking changes detected in minor/patch versions:

⚠️ Breaking changes detected:
❌ Breaking changes in non-major version!
Consider bumping to v2.0.0

Action:

If intentional: Bump to major version
If unintentional: Revise changes to maintain compatibility

"ANTHROPIC_API_KEY environment variable not set"

AI enhancement requires an API key:

# Get API key from Anthropic Console
# https://console.anthropic.com/

# Set environment variable
export ANTHROPIC_API_KEY=sk-ant-api03-...

# Or add to shell config
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc
source ~/.bashrc

Workflow Not Triggering

For changelog generation:

Ensure tag matches pattern v*.*.* (e.g., v1.0.0, not 1.0.0)
Check GitHub Actions tab for workflow runs
Verify workflows are enabled in repository settings

For breaking change detection:

Ensure PR modifies files in packages/server/api/src/**
Check the "Files changed" tab on the PR
Wait a few minutes for workflow to complete

Advanced Usage

Comparing Arbitrary Commits

Compare any two commits (not just tags):

# Generate spec from commit A
git checkout abc123
cd packages/server/api && pnpm run generate:openapi
cp dist/openapi.json /tmp/spec-a.json

# Generate spec from commit B
git checkout def456
pnpm run build && pnpm run generate:openapi
cp dist/openapi.json /tmp/spec-b.json

# Compare
oasdiff diff /tmp/spec-a.json /tmp/spec-b.json --format text

Filtering Changes

oasdiff supports filtering by specific paths or operations:

# Only show changes to /flows endpoints
oasdiff diff prev.json curr.json --filter-path="/api/v1/flows.*"

# Only show POST/PUT/DELETE (mutations)
oasdiff diff prev.json curr.json --filter-method="POST,PUT,DELETE"

JSON Output for Automation

Generate machine-readable output:

# JSON format for programmatic use
oasdiff diff prev.json curr.json --format json > changes.json

# Parse with jq
cat changes.json | jq '.pathsDiff.added | length'
# Output: 5 (number of new endpoints)

Custom AI Prompts

Modify the AI enhancement prompt for different audiences:

# Edit scripts/generate-ai-changelog.py
# Find the prompt variable (line ~743)

prompt = f"""Please provide an API changelog for {version}...

<custom_instructions>
Focus on: [Frontend developers / Backend integrators / Mobile app teams]
Include: [Code examples in JavaScript / Python / cURL]
Tone: [Technical / Beginner-friendly / Executive summary]
</custom_instructions>
"""

Integration with Development Process

Sprint Planning

Use changelogs to estimate migration effort for API consumers:

# Preview breaking changes for next release
./scripts/generate-changelog.sh v1.0.0 main

# Estimate migration work based on breaking changes count

Release Notes

Combine automated changelogs with manual release notes:

# Release v1.1.0

## Highlights
- New flow execution API
- Improved connection health monitoring
- Performance improvements

## Complete API Changes
See [API Changelog](/changelogs/CHANGELOG-v1.1.0)

## Breaking Changes
⚠️ None - fully backward compatible

Deprecation Workflow

When deprecating an endpoint:

v1.0.0: Add new endpoint, mark old as deprecated in docs
v1.1.0: Changelog shows both endpoints exist
v2.0.0: Remove old endpoint, changelog shows breaking change

# Changelog will show:
# v1.1.0: Added new endpoint (no breaking changes)
# v2.0.0: Removed deprecated endpoint (breaking change)

Tool	Purpose	Documentation
SDK Generation	Auto-generate TypeScript/Python SDKs	SDK Guide
Mock Servers	Prism-based API mocking	Mock Server Guide
Postman Collections	GUI-based API testing	Postman Guide

Reference

Command Reference

# Generate standard changelog
./scripts/generate-changelog.sh <prev> <curr>

# Generate AI-enhanced changelog
python3 scripts/generate-ai-changelog.py <prev-spec> <curr-spec> <version> <output>

# Check for breaking changes
oasdiff breaking <prev> <curr> --format text

# Generate diff
oasdiff diff <prev> <curr> --format text

# Changelog format options
oasdiff changelog <prev> <curr> --format markdown
oasdiff changelog <prev> <curr> --format json

File Locations

File	Purpose
`scripts/generate-changelog.sh`	Main changelog script
`scripts/generate-ai-changelog.py`	AI enhancement script
`.github/workflows/changelog-generation.yml`	Auto-generate on tags
`.github/workflows/api-breaking-changes.yml`	PR breaking change detection
`requirements-changelog.txt`	Python dependencies
`docs-new/changelogs/`	Generated changelog output

Environment Variables

Variable	Required	Purpose
`ANTHROPIC_API_KEY`	Optional	Claude API key for AI-enhanced changelogs
`OASDIFF_BIN`	Optional	Path to oasdiff binary (auto-detected)

Next Steps

Try generating a test changelog
Configure ANTHROPIC_API_KEY for AI enhancement (optional)
Create your first version tag when ready to release
Review generated changelogs in Docusaurus

For more information, see:

API Changelogs - View generated changelogs
API Reference - Browse API endpoints
SDK Generation - Auto-generate client libraries

Questions? Contact the Platform team or open an issue on GitHub.

Overview​

Tool 1: Changelog Generation Script​

Purpose​

Location​

Usage​

Example​

What It Does​

Output Format​

Prerequisites​

Troubleshooting​

Tool 2: AI-Enhanced Changelog Script​

Purpose​

Location​

Usage​

Example​

Prerequisites​

What Makes It Different​

Example Output​

Triggers​

PR Comments​

Testing Before PR​

Tool 4: Automatic Release Changelogs​

Purpose​

Location​

How It Works​

Manual Trigger​

Development Workflow​

During Development​

Before Creating PR​

During Code Review​

At Release Time​

Configuration​

GitHub Secrets (Optional AI Enhancement)​

Local Setup​

Best Practices​

1. Always Check for Breaking Changes​

2. Document Breaking Changes​

3. Use Semantic Versioning​

4. Keep OpenAPI Specs Updated​

5. Test Changelog Generation Locally​

Troubleshooting​

"oasdiff: command not found"​

"Could not generate OpenAPI spec for v1.0.0"​

"Breaking changes in non-major version"​

"ANTHROPIC_API_KEY environment variable not set"​

Workflow Not Triggering​

Advanced Usage​

Comparing Arbitrary Commits​

Filtering Changes​

JSON Output for Automation​

Custom AI Prompts​

Integration with Development Process​

Sprint Planning​

Release Notes​

Deprecation Workflow​

Related Tools​

Reference​

Command Reference​

File Locations​

Environment Variables​

Next Steps​

Overview

Tool 1: Changelog Generation Script

Purpose

Location

Usage

Example

What It Does

Output Format

Prerequisites

Troubleshooting

Tool 2: AI-Enhanced Changelog Script

Purpose

Location

Usage

Example

Prerequisites

What Makes It Different

Example Output

Triggers

PR Comments

Testing Before PR

Tool 4: Automatic Release Changelogs

Purpose

Location

How It Works

Manual Trigger

Development Workflow

During Development

Before Creating PR

During Code Review

At Release Time

Configuration

GitHub Secrets (Optional AI Enhancement)

Local Setup

Best Practices

1. Always Check for Breaking Changes

2. Document Breaking Changes

3. Use Semantic Versioning

4. Keep OpenAPI Specs Updated

5. Test Changelog Generation Locally

Troubleshooting

"oasdiff: command not found"

"Could not generate OpenAPI spec for v1.0.0"

"Breaking changes in non-major version"

"ANTHROPIC_API_KEY environment variable not set"

Workflow Not Triggering

Advanced Usage

Comparing Arbitrary Commits

Filtering Changes

JSON Output for Automation

Custom AI Prompts

Integration with Development Process

Sprint Planning

Release Notes

Deprecation Workflow

Related Tools

Reference

Command Reference

File Locations

Environment Variables

Next Steps