API Breaking Change Review

Template Overview

Evolving enterprise APIs without disrupting mission-critical client integrations requires disciplined deprecation cadences, backward compatibility bridges, and clear developer communications. The API Breaking Change Review template organizes schema modifications, endpoint sunset schedules, and client telemetry into a verifiable Markdown record.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "API Deprecation Review: [API Version / Endpoint Group]"
date: [YYYY-MM-DD]
api_architect: "[[Staff API Architect]]"
product_lead: "[[Platform Product Manager]]"
developer_relations: "[[Head of Developer Relations]]"
target_deprecation_date: [YYYY-MM-DD]
target_sunset_date: [YYYY-MM-DD]
impact_tier: "Tier-1 / High External Customer Impact"
tags: [api, deprecation, breaking-changes, developer-platform, governance]
---

# API Breaking Change & Deprecation Review — [API Version]

## 1. Proposed Schema Modifications & Rationale
- **Target Endpoints:** `/v1/transcripts`, `/v1/meetings/{id}/audio`
- **Breaking Modification:** Transitioning from synchronous JSON payload return to asynchronous streaming SSE endpoint.
- **Architectural Motivation:** Eliminates 30-second gateway timeout errors on large meeting transcripts and reduces memory pressure by 80%.

## 2. Impact Analysis & Client Telemetry
| Client Cohort | Active Call Volume | Primary Integration Type | Migration Complexity |
|---|---|---|---|
| **Enterprise Integrators** | 1.4M requests/day | Backend Server Webhooks | Moderate (SDK update required) |
| **Mobile Applications** | 800k requests/day | Native iOS/Android SDKs | High (Requires App Store update) |
| **Third-Party Plugins** | 120k requests/day | Community Obsidian Plugin | Low (Direct drop-in replacement) |

## 3. Deprecation Window & Sunset Cadence
- **Day 0 (Announcement):** Deprecation notice headers (`Sunset: [Date]`, `Deprecation: true`) added to HTTP responses.
- **Day 30:** Beta release of updated multi-language client SDKs (TypeScript, Python, Go, Swift).
- **Day 90:** Targeted email outreach to top 20 enterprise API consumers still querying legacy endpoints.
- **Day 180 (Brownout Testing):** 1-hour planned service degradation windows to surface un-migrated systems.
- **Day 270 (Hard Sunset):** Permanent deactivation of legacy endpoints with HTTP 410 Gone.

## 4. Review Decisions & Action Items
- [ ] [[API Architect]] Finalize OpenAPI 3.1 specification for `/v2/` streaming endpoints.
- [ ] [[Developer Relations]] Author end-to-end migration guide and interactive code snippets.
- [ ] [[Platform PM]] Deliver 9-month sunset timeline to Customer Success leadership.

Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

---
title: "API Deprecation Review: Storage V1 Endpoints"
date: 2026-10-10
api_architect: "[[Noah Takahashi]]"
product_lead: "[[Elena Rostova]]"
developer_relations: "[[Liam O'Connor]]"
target_deprecation_date: 2026-11-01
target_sunset_date: 2027-05-01
impact_tier: "Tier-2"
tags: [api, deprecation, breaking-changes, developer-platform, governance]
---

# API Breaking Change & Deprecation Review — Storage V1

## 1. Architectural Review
Noah Takahashi presented the deprecation proposal for legacy raw binary uploads in favor of pre-signed multipart uploads. The committee approved the change, citing improved reliability for audio uploads exceeding 1 GB.

## 2. Brownout Strategy
Approved scheduling two brownout tests at 90 days and 120 days post-announcement to verify customer resilience before the permanent sunset date.

## 3. Action Items
- Liam O'Connor will publish Python and TypeScript migration recipes by October 25.

When to Use and When to Avoid

When to Use

• Use prior to approving breaking changes, parameter removals, or endpoint deprecations.
• Use to establish formal deprecation windows, telemetry tracking, and SDK upgrade paths.
• Use to coordinate engineering, developer relations, and customer communication strategies.

When to Avoid

• Avoid for backward-compatible non-breaking additions (e.g., adding an optional field).
• Avoid for internal private function refactors.

On-Device AI Integration

Summarize your recording in Oyma with this local instruction:

Analyze the API deprecation review audio:
1. Outline proposed breaking changes, technical rationales, and affected endpoints.
2. Summarize client telemetry assessments, enterprise customer impacts, and SDK update requirements.
3. Extract the agreed deprecation and sunset timeline, brownout test dates, and responsible leads.
Output in clean, structured Markdown.

Your data remains securely on your Mac with zero cloud exposure.