API versioning is one of those topics that sounds straightforward until you have actual clients depending on your service. Then every breaking change becomes a coordination problem across teams, partners, and external developers who all built against your old contract. The Professional Cloud Architect exam expects you to know how to handle this without forcing every consumer to upgrade in lockstep with you.
The core rule is simple. When you introduce a non-backward-compatible change, increment the version number. That gives existing clients a stable contract to keep using while new clients adopt the new version on their own timeline.
Not every API change requires a new version. Adding a new optional field, a new endpoint, or a new response attribute is usually safe because existing clients ignore what they do not know about. Those are backward-compatible additions and they belong in the current version.
The changes that force a version bump are the ones that break existing client code. Removing a field clients depend on. Renaming a field. Changing a field's type from string to integer. Tightening validation so requests that used to succeed now fail. Restructuring a response so the path to a value changes. Anything that would cause a client running yesterday's code to fail today is a non-backward-compatible change, and shipping it under the current version number breaks production for every consumer who has not been warned.
The point of versioning is to decouple your release cadence from your clients' upgrade cadence. If you ship v2 and immediately turn off v1, you have not really versioned anything. You have just renamed a forced migration.
Real versioning means v1 keeps working while v2 is available. Clients see the new version, read the changelog, schedule the migration, test against v2 in their own environment, and switch when they are ready. Some clients move within a week. Some take a quarter. Some external partners take a year. Supporting both versions concurrently is what makes the transition voluntary on the client's side.
That obviously costs you something. You are running two code paths, fixing bugs in two places, and writing tests for both contracts. Most teams handle this by setting an explicit deprecation window, something like twelve or eighteen months, after which the old version is retired. The window is announced when v2 ships, not when you decide you want to delete the old code.
There are a few common conventions. The version can live in the URL path, like /v1/users and /v2/users. It can sit in a custom header, like API-Version: 2. It can be part of the Accept header using media type versioning, like Accept: application/vnd.myapi.v2+json. Each has trade-offs around caching, discoverability, and how easy it is to test from a browser, but the architectural point is the same. The version is part of the contract, and the server routes the request to whichever implementation matches.
You will not be asked to memorize header syntax. The exam tests whether you understand the design principle. A scenario will describe a team that needs to evolve an API while existing clients keep working, and the right answer will be the one that introduces a new version while continuing to support the old one. Wrong answers will either force every client to migrate at once or ship a breaking change under the existing version. Recognize the pattern and the question answers itself.
The same principle shows up when the exam talks about Cloud Endpoints, Apigee, or any managed API gateway on Google Cloud. Those products give you the routing and lifecycle tools to run multiple versions side by side. The product names change but the underlying decision is the architectural one. Do not break the existing contract, and give clients time to move.
My Professional Cloud Architect course covers API versioning alongside the rest of the architecture and compliance material.
