An API is a promise about behavior. Keeping every URL alive does not keep that promise. Clients depend on field meanings, defaults, accepted inputs, error behavior and how long old behavior will last. Change any of those and you can break consumers while every endpoint still returns 200. Microsoft puts it plainly: “An API serves as a contract between a service and clients or consumers of that service” (Microsoft Learn, API Design).
What the promise actually covers
Treat the contract as everything a reasonable client can observe and build on. Google’s compatibility guidance (AIP-180) frames the test as whether existing clients keep working against newer servers. It treats visible semantic changes likely to break reasonable user code as breaking changes. Microsoft’s connector guidance lists changes to the meaning or behavior of an input, output or operation among breaking changes to an OpenAPI-described contract (Implement versioning operations).
As an Amazon Associate I earn from qualifying purchases.
- Resource shapes: field names, types, value formats and nesting.
- Accepted inputs: parameters, allowed values, and which fields are required.
- Meanings and defaults: what a field represents and what happens when a client omits it.
- Serialization and algorithms: how values are encoded and computed.
- Operation semantics: side effects, retry behavior, and whether work is synchronous.
- Lifecycle: how long a version lives and how change is announced.
The practical test is to judge behavior consumers can observe, not just whether a schema diff looks harmless or an endpoint responds.
Which changes break clients even when the endpoint survives
| Change | Why it breaks the promise |
|---|---|
| Removing a field, parameter or previously supported input | AIP-180 says removing a component within the same major version is backwards incompatible. Microsoft lists removed parameters and dropped inputs as breaking. |
| Renaming a field | AIP-180 treats a rename as a removal plus an addition. |
| Changing a field’s meaning, type, value format, default or serialization | Clients parse and interpret these. AIP-180 says existing types, formats, algorithms, defaults and serialization should stay stable. |
| Adding a new required request field | Existing requests become invalid. AIP-180 says not to add new required fields to existing request messages or resources. |
| Changing what an operation does | Microsoft counts changed operation meaning or behavior as breaking, even if the signature is identical. |
Can adding a field break an API?
Yes, sometimes. Additive changes are not automatically safe. AIP-180 allows new components in the same major version only if clients unaware of them keep their previous behavior. A new optional field that alters how existing requests are treated, or a new response value that older clients cannot handle, can still cause failures. A new field is compatible when ignoring it leaves an old client’s experience unchanged.
#1 Best Overall
Keep internal refactors out of the contract
Microsoft advises modeling the domain rather than exposing internal database structure, and notes that implementation changes often should not require API changes (API Design). A mapping layer between storage and the client-facing model lets you migrate tables without touching consumers. Tie an API change to a new client-visible capability, not to a refactor or database migration alone. If a schema change leaks into responses, you have coupled clients to your internals.
Operational semantics are part of the promise
Microsoft’s guidance (Web API Design Best Practices) recommends using HTTP methods consistently with their meaning. It also recommends considering idempotency for side-effecting operations, so identical retries are safer. For work that is accepted but not finished, it describes returning HTTP 202 Accepted. Clients build retry logic and polling around these behaviors. Switching a synchronous call to asynchronous, or making a safe retry unsafe, breaks them as surely as removing a field.
Rank #2
- Used Book in Good Condition
Choosing a versioning approach
Microsoft documents four REST patterns, each with trade-offs:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errors| Approach | Strengths | Costs |
|---|---|---|
| URI versioning | Explicit and easy to route | Paths proliferate; links must be versioned |
| Query string | Stable resource path; cacheable per URI and query combination | Needs parsing and routing logic; Microsoft notes caching limits in some older browsers and proxies |
| Header | Stable URI | Clients must send a header, the server must inspect it, and links must account for header context |
| Media type (Accept) | Versions the representation; works with hypermedia links | Requires content negotiation and awareness of cache variation |
Compare them on client complexity, link and resource stability, caching, server routing, and how many versions your team can test and operate. Versioning does not make an unsafe change safe. You must still preserve the old contract for its consumers.
Plan the lifecycle, not just the version label
AIP-185 says different versions should coexist for a reasonable transition period, and older versions should have a reasonable, well-communicated deprecation period before shutdown. The guidance gives no universal duration, so set one based on your situation:
- Consumer control: public clients you cannot force to upgrade need longer windows than internal services you deploy together.
- Stability commitments: what you have promised in docs or agreements.
- Operational capacity: how many concurrent versions you can test and run.
AIP-180’s own scope matters here. It targets APIs whose producers do not control when consumers update. An internal API with coordinated, enforceable deployments can set requirements suited to that context. Its line that “Existing client code must not be broken by a service updating to a new minor or patch release” applies to releases within the same major version.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.A pre-release checklist
- Diff the schema, then also diff behavior: defaults, validation, error responses, ordering, serialization.
- Check that no required request input was added and nothing was removed or renamed in the same major version.
- Confirm that old clients, unaware of any new field, behave as before.
- Confirm the change comes from a client-visible need, not an internal refactor leaking out.
- If the change is genuinely breaking, ship a new major version, run both together, and announce a deprecation period for the old one.
- Document retry, idempotency and asynchronous behavior as part of the contract.
Neither source offers measured data on how much these practices reduce incidents. They are published design guidance, so adapt them to who consumes your API and how much control you have over them.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
