API Changelogs

Automated version history for Staqr Platform APIs

This section contains automatically generated changelogs for the Staqr Platform API. Changelogs are created by comparing OpenAPI specifications between version releases, ensuring complete and accurate documentation of all API changes.

---

How Changelogs Are Generated

Changelogs are automatically generated using oasdiff whenever a new version tag is pushed to the repository.

The Process

graph LR
    A[Push Version Tag] --> B[GitHub Actions Triggered]
    B --> C[Checkout Previous Version]
    C --> D[Generate Previous OpenAPI Spec]
    D --> E[Checkout Current Version]
    E --> F[Generate Current OpenAPI Spec]
    F --> G[oasdiff Compare Specs]
    G --> H[Generate Markdown Changelog]
    H --> I[Commit to docs-new/changelogs/]

What's Included

Each changelog documents:

• New Endpoints: APIs added in this version
• Modified Endpoints: Changes to existing APIs (parameters, responses, etc.)
• Removed Endpoints: Deprecated/removed APIs
• Breaking Changes: Changes that require code updates (highlighted with ⚠️)
• Migration Guides: How to adapt code for breaking changes (AI-enhanced only)

---

Reading Changelogs

Standard Changelogs

Technical diffs showing exact OpenAPI schema changes:

## POST /api/v1/flows/{flowId}/execute

- endpoint added
- request body: application/json
- response: 200 (FlowExecutionResponse)

Best for: API developers who need precise technical details

AI-Enhanced Changelogs

Human-friendly release notes with context and migration examples:

## Flow Management

### ✨ New: Execute Flow by ID

You can now trigger flows programmatically using the new execute endpoint.

**Before:**
Flows could only be triggered by webhooks or schedules.

**After:**
```typescript
const result = await api.flows.execute(flowId, {
  payload: { customerId: '123' }
});

Migration: No changes required for existing code.

**Best for:** Developers integrating with Staqr who need to understand impact

---

## Version History

Changelogs are available for these versions:

{/* This section will be auto-populated as versions are released */}

**Latest Version:** Check below for the most recent API changelog

**All Versions:** See the sidebar for complete version history →

---

## Breaking Changes

### What Are Breaking Changes?

Breaking changes require API consumers to update their code. Examples:

| Change Type | Impact | Example |
|-------------|--------|---------|
| **Removed endpoint** | Code calling it will fail | `DELETE /api/v1/old-endpoint` removed |
| **Removed parameter** | Requests missing it may fail | `customerId` parameter removed from request |
| **Changed response type** | Parsing code needs updates | Response changed from `string` to `{ id: string }` |
| **Required new parameter** | Existing calls will be rejected | New required parameter `sellerId` added |

### Breaking Change Detection

Our CI/CD automatically detects breaking changes in pull requests:

1. **PR created** modifying API code
2. **GitHub Actions** compares base branch vs PR branch OpenAPI specs
3. **Comment posted** on PR if breaking changes detected
4. **Warning shown** if breaking changes found in non-major version

**Protection:** Prevents accidental breaking changes from being merged

---

## For Developers

### Manual Changelog Generation

If you need to generate a changelog manually (e.g., to preview changes before tagging):

```bash
# Compare two version tags
./scripts/generate-changelog.sh v1.0.0 v1.1.0

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

AI-Enhanced Generation

For human-friendly release notes:

# Set your Anthropic API key
export ANTHROPIC_API_KEY=sk-ant-...

# Generate AI-enhanced changelog
python3 scripts/generate-ai-changelog.py \
    packages/server/api/dist/openapi.json \
    packages/server/api/dist/openapi-previous.json \
    v1.1.0 \
    docs-new/changelogs/CHANGELOG-v1.1.0-ai.md

Requirements: Python 3.x and anthropic package

Testing Your Changes

Before releasing, check what changes your PR introduces:

# Generate current spec
cd packages/server/api
pnpm run generate:openapi

# Compare against main branch
oasdiff diff \
    /path/to/main-branch/openapi.json \
    dist/openapi.json

See: API Versioning Guide for detailed tooling documentation

---

Versioning Strategy

Staqr follows Semantic Versioning for API releases:

Version Format	When to Use	Example
MAJOR.x.x	Breaking changes	v1.x.x → v2.0.0
x.MINOR.x	New features (backward compatible)	v1.0.x → v1.1.0
x.x.PATCH	Bug fixes (backward compatible)	v1.0.0 → v1.0.1

Rule: Breaking changes MUST bump the major version

---

Technical Details

Tools Used

• oasdiff: OpenAPI diff and breaking change detection
• OpenAPI Specification: API contract format
• Claude API: AI enhancement (optional)

Source Code

File	Purpose
scripts/generate-changelog.sh	Main changelog generation script
scripts/generate-ai-changelog.py	AI-enhanced changelog script
.github/workflows/changelog-generation.yml	Auto-generate on version tags
.github/workflows/api-breaking-changes.yml	PR breaking change detection

Repository: GitHub - Staqr Platform

---

Feedback

Found an issue with a changelog? Have suggestions for improvement?

• GitHub Issues: Report a problem
• Internal: Contact the Platform team

---

Changelogs are automatically updated when new versions are released. No manual maintenance required.