API Breaking Change Migration Guide Brief

Role: Staff Technical Writer specializing in Developer Experience and API Governance

Context

• Target Service: {{api_service_name}}
• Release Version: {{target_version}}
• Summary of Changes: {{breaking_changes_summary}}
• Primary Audience: {{target_audience}}
• Migration Window: {{migration_window}}
• Rollback and Fallback Strategy: {{fallback_strategy}}

Task

Generate a structured API migration documentation brief that clearly defines deprecation timelines, payload transformations, code migration patterns, and risk mitigation strategies for {{api_service_name}} {{target_version}}.

Method

1. Analyze {{breaking_changes_summary}} to identify affected endpoints, altered schema fields, and removed parameters.
2. Define developer personas across {{target_audience}} to tailor technical complexity and code sample requirements.
3. Construct a deprecation schedule aligned with {{migration_window}}, identifying hard cutoff dates and feature freeze milestones.
4. Draft side-by-side payload transformation schemas showing legacy versus {{target_version}} request and response objects.
5. Detail specific error codes and diagnostics that indicate deprecated endpoint utilization.
6. Formulate testing and verification recipes for developers validating the upgrade in staging environments.
7. Detail step-by-step contingency operations referencing {{fallback_strategy}} for unresolvable integration failures.

Constraints

• MUST include explicit before-and-after schema comparison tables.
• MUST NOT use abstract pseudocode; all structural examples must reflect valid JSON or standard REST conventions.
• Technical instructions must strictly accommodate {{target_audience}} operational competencies.
• Content must be organized for rapid scanning by on-call engineers.
• Total brief length must stay between 400 and 650 words.

Output format

Provide the brief using the following explicit section headers:

1. Executive Migration Overview (Max 75 words)
2. Deprecation Schedule & Milestones (Bullet points with explicit dates/phases)
3. Schema & Endpoint Diff Specification (Markdown table with Legacy, New, and Action Required)
4. Verification & Testing Protocol (Step-by-step list)
5. Fallback & Telemetry Guidelines (Brief operational procedure)

Self-review

• Check that every item in {{breaking_changes_summary}} is mapped to a tangible migration action.
• Verify that {{migration_window}} milestones contain explicit operational phases.
• Confirm that no undefined API terminology remains unexplained.