Breaking SaaS API Changes: What to Share in Public

The short answer

Explain a breaking SaaS API change by naming the exact compatibility difference, affected consumers, required action, timing, and verification steps. Link public reasoning to a maintained migration guide. Separate notice delivery, version adoption, and a correctly completed dependent task; a successful HTTP response alone does not establish a working migration.

When building in public through a breaking SaaS API change, explain the exact compatibility difference, who depends on it, what they must change, and how to verify their integration afterward. Link the public reasoning to a maintained migration guide. A successful request or a popular announcement does not establish that a customer’s dependent workflow still works.

Your followers may want to understand the product decision. An integrator needs to know whether tomorrow’s room search, report, or automation will behave differently. Give both readers an answer without making the affected person reconstruct instructions from a month of progress posts.

This guide adds a fictional room-booking API example and a version-specific action table. The API, sample responses, proposed updates, and checks are illustrative. No API calls, customer migration, or product tests were performed for this article.

Name the compatibility change before explaining the benefit

A breaking change can require a consumer to alter an integration that previously worked. It need not be an endpoint disappearing. GitHub’s REST API versioning documentation includes renamed response fields, changed field types, newly required parameters, and changed authorization requirements among its breaking-change examples.

Start the public explanation with that difference. “We improved the room API” hides the work someone else must do. “The new room API represents capacity as an object; consumers must select the appropriate capacity field” gives an integrator a concrete reason to read further.

Then explain why you chose the change and which alternative you considered. Perhaps one old value can no longer express the product’s different room layouts. That is a useful building-in-public decision: readers can inspect the tradeoff between a clearer model and migration effort. Do not imply that a cleaner model automatically makes existing integrations better.

An internal refactor that preserves external behavior has a different communication job. The guide to explaining SaaS technical debt in public covers that case. Here, the external contract intentionally changes, so the required consumer action belongs near the opening.

Before choosing the incompatible route, explain whether you considered an additive alternative. In the room example, the founder could consider retaining the existing seated-capacity integer while adding separate layout information. Whether that design is suitable depends on the real API and its consumers; this article does not establish that it is safe. The public value is showing why the chosen benefit justifies asking integrators to change.

Keep that reasoning separate from migration instructions. Readers can disagree with the design while still needing a precise description of how to keep their integration working. Feedback about the tradeoff should not obscure the current supported behavior.

State your versioning policy without borrowing another company’s promise

Version labels help only when readers know what they mean. Semantic Versioning 2.0.0 assigns incompatible public API changes a major version increment for versions 1.0.0 and above. Its initial-development rules for 0.y.z are different. That convention applies when software adopts it; a hosted API does not necessarily use SemVer.

GitHub, for example, uses date-based REST API versions. Its current documentation describes a support window of at least 24 months for the previous version after a newer version is released, with documented exceptional interventions. That is GitHub’s policy, not a universal notice period or a commitment a small SaaS should copy.

Write your own supported versions, how consumers select them, and what happens when selection is omitted. Distinguish the new version becoming available from the old version becoming unavailable. Choose timing around the work real integrators must complete and any commitments your product has already made.

Deprecation is also different from shutdown. RFC 9745, published in March 2025 describes deprecation as lifecycle information that does not itself change the resource’s behavior. It separately discusses the Sunset header for expected unavailability. Those mechanisms can support an API’s documented policy; their existence does not mean every service implements them.

Show the old and new behavior with a synthetic example

Imagine a fictional room-booking SaaS. Its v1 room response uses capacity to mean seated capacity. The founder wants v2 to support both seated and standing layouts. The browser booking interface remains unchanged in this scenario; external consumers choosing v2 must adapt to a new response shape.

Simplified v1 response:

{
  "id": "room_example",
  "capacity": 6
}

Simplified v2 response for the same invented room:

{
  "id": "room_example",
  "capacity": {
    "seated": 6,
    "standing": 10
  }
}

The migration instruction is more precise than “update to v2.” A client finding seated meeting rooms must read capacity.seated instead of the old capacity integer. A client supporting standing events needs a deliberate layout choice. Treating standing capacity as a replacement for seated capacity would change the meaning of the user’s search.

This is the useful public lesson: a response can arrive successfully while the consuming application interprets it incorrectly. Depending on its implementation, an old filter might reject a room, display an object, or fail elsewhere. These are possible failure modes, not observed test results.

A real provider example shows the level of specificity to aim for. In GitHub’s breaking-change guide for REST API version 2026-03-10, the removal of the deprecated rate property names the affected GET /rate_limit endpoint and directs integrations to resources.core. The documentation provides an exact replacement rather than asking readers to infer it from a release headline. This example establishes the published guidance, not how successfully users migrated.

Give each reader the action that matches their version

For the fictional room API, an action table could look like this. It assumes the founder has deliberately kept v1 available during the transition. It does not describe an actual product or support commitment.

Include unversioned consumers in the real analysis. If an omitted version silently selects a changing default, “you have not opted in” may be a false reassurance. Explain the actual default and its transition behavior. If you cannot determine which version a consumer uses, keep that uncertainty visible and provide a way to establish it.

Keep synthetic examples minimal but complete enough to show the changed meaning. Remove real account identifiers, access tokens, private room names, and customer payloads. A public sample needs the compatibility difference, not a screenshot of someone’s production request.

Publish the reasoning beside a durable migration guide

Use one maintained guide for the operational details: affected endpoints and versions, before-and-after behavior, selection method, availability dates with time zone, required changes, verification steps, and a support route. Mark planned dates as planned. If the old behavior will stop, describe what consumers should expect at that point.

Link that guide from the public changelog and your founder update. The guide to using a public SaaS changelog for feature adoption explains the durable release record. A breaking change needs the additional compatibility instructions shown here, including what people must do to preserve an existing task.

Affected integrators also need communication through the channels your product uses for operational changes. A follower seeing your public post is not evidence that the person maintaining an integration received the notice. Keep contact details and individual migration status private.

The following is proposed planning-stage copy for the invented room API. It assumes the maintained guide and contact route exist before the founder uses this wording:

We’re preparing a new room API version because one capacity value cannot describe both seated meetings and standing events. In v2, capacity becomes an object with separate seated and standing values. Integrations for seated meetings will need to read capacity.seated.

Our plan keeps v1 available during a transition, while the browser booking flow stays the same. The migration guide will list the availability and retirement dates, version-selection method, and checks. We have not announced those dates yet.

We’ll publish the confirmed schedule and contact affected integrators before the planned transition begins. Our check is whether their room searches still return the correct rooms for the selected layout, not simply whether v2 requests succeed.

That post makes the tradeoff and unfinished work explicit. Once dates are confirmed, replace the planning language with the actual schedule and link. Do not leave an old preview as the only discoverable instruction after the new behavior becomes available.

Report migration evidence separately from announcement reach

Before calling the transition complete, distinguish three observations:

• Notice: the relevant technical contact received the specific change and instructions. A social impression does not establish this.

• Version: the integration now selects the intended version and uses its response format. A deployment ticket alone does not establish this.

• Task: the dependent workflow produces the intended result under the cases checked. An HTTP 200 response alone does not establish this.

For the fictional room search, proposed checks include whether a six-person seated meeting includes the example room, whether a seven-person seated meeting excludes it, and whether an eight-person standing event uses the standing value. Also check the product’s actual missing-data and error cases. These are suggested checks, not a complete test plan or tests conducted for this article.

Low traffic can make completion hard to judge. A monthly integration may be absent from a short observation window. An unidentified consumer may still exist. Describe the population and time period your evidence covers, and keep unresolved cases separate from confirmed migrations. Do not publish private account lists to make the follow-up look more concrete.

If a problem changes the schedule, update the maintained guide and linked notices. Explain what changed in the plan and who still needs to act. Any real rollback or compatibility route must be checked against the product’s actual behavior; a public promise is not proof that recovery will work.

A useful follow-up can explain which compatibility assumption failed, how the instructions changed, and what remains uncertain. It need not claim that the transition increased trust, retention, or revenue. Those outcomes require different evidence.

Buildside’s About page describes sharing SaaS progress and finding useful collaborators. A versioning decision can belong in that public record when it explains a real product tradeoff. Buildside publishes this Journal; the suggested workflow does not imply that Buildside tests APIs, delivers operational notices, or verifies migrations.

Questions founders ask next

Does a major version number explain a breaking API change?

It can signal incompatibility when the product follows that versioning convention. Consumers still need the exact affected behavior, selection method, required changes, timing, and verification instructions.

How much notice should a SaaS API migration give?

Use your documented policy, existing commitments, and the work affected integrators need to complete. Another provider’s support window is an example of its policy, not a universal duration to copy.

Can I announce the decision before migration dates are confirmed?

Yes, if the post clearly describes planning and says which details remain undecided. Do not imply that a new version is available or an old version has a retirement date until those facts are confirmed. Follow up with the maintained guide and actual schedule.

Sources

GitHub Docs: REST API versions and compatibility policy

GitHub Docs: Breaking changes and version-specific migration instructions

Semantic Versioning: Version 2.0.0 specification

RFC 9745: Deprecation, lifecycle information, and Sunset

Buildside: About the community and publishing approach

Frequently asked questions

A note from Uriel Bitton

This guide combines primary API documentation with an original fictional room-booking example. It reports no firsthand API tests, customer migrations, or business outcomes. Buildside publishes this Journal.

Keep building with us

Get practical founder lessons and product updates in your inbox.

Subscribe or Join Buildside.

Keep reading