Skip to content
WorkspaceTemplates
The first pages of the API Change Proposal template

API Change Proposal

Document template for Google Docs and Word

Make a copy in Google Docs
Type
Document
Price
Free
Pages
7 · US Letter
Style
Modern
Difficulty
Beginner
Updated
November 6, 2026

Every page (7)

Overview

A change to a public API fails when consumers learn about it from a broken build. This proposal puts the change, the people it affects and the way old calls keep working in front of reviewers before anyone writes code. It runs from scope, through consumers and a compatibility reference, to migration gates and a dated timeline.

The sample is RFC-0047 from Yarrowfield Systems: replace offset pagination on the events list with cursors, cutting p95 latency from 840 ms to 590 ms. Six teams are affected, a shim keeps old calls working for 120 days, and the decision is due March 24, 2027. Replace the endpoint, teams, figures and dates with your own.

Useful for

  • An API engineer proposing new pagination on a busy endpoint and asking affected teams to object in writing
  • A tech lead planning a three-release migration with a compatibility shim and a clear removal date
  • An architect recording why an API changed so the next team can read the decision and its alternatives

What's included

  • A scope page comparing what changes and what does not, with assumptions and a callout on the breaking change
  • A consumers page with call volume by team and two profiles of the people most affected
  • A compatibility page documenting the operation, its parameters, request and response examples
  • A migration page with a release timeline and what happens at each gate
  • A roadmap with phases, owners and a month-by-month Gantt, plus a key dates page with a review calendar
  • A make-it-yours guide page with five steps for replacing the sample

How to use it

  1. 1

    Click Make a copy in Google Docs, then confirm on the Google page. The copy is saved to your own Google Drive.

  2. 2

    Set the RFC number, author and decide-by date, then rewrite the scope so a reader can accept or object after one page.

  3. 3

    List the teams and calls affected, notify their leads before circulating, and document the old and new call with parameters.

  4. 4

    Set the migration gates, the shim length and the removal date, and record each objection with your response.

  5. 5

    Delete the guide page, share the RFC and mark the final status as accepted, rejected or deferred once decided.

What you need

Requirements

  • A Google account with access to Google Drive

Works with

  • Google Docs
  • Microsoft Word (download the .docx)

Questions

How long should the review window be?

Five to ten working days is typical. The sample gives eight, from March 12 to March 24, 2027, with a written cutoff for objections so the decision date does not drift.

How long should a compatibility shim last?

Between 90 and 180 days is common. The sample keeps old offset calls working for 120 days across three releases, with a warning header added at the midpoint.

Are the company and figures real?

No. Yarrowfield Systems, its people, the RFC and every figure and date are fictional sample data. Replace them with your own details before you circulate a proposal.

  • #api-change-proposal
  • #rfc-template
  • #api-deprecation
  • #engineering-rfc
  • #migration-plan
  • #google-docs
  • #platform-team

Related templates

More Google Docs templatesMore developer workflows templates

Also in Developer workflows

All developer workflows templates
Get this template

    What you get

      Use this templateSee full details

      Preparing your template…