API versioning and lifecycle: how to change an API without breaking clients

An API is a contract between the bank and its clients, and once clients have built against it, the bank cannot change it casually. Versioning is how the bank evolves an API while keeping existing clients working. The most common approach for payment APIs is versioning in the path, such as /v1/payments and /v2/payments, because it is visible, easy to route, and easy to test. For a business analyst, the requirement is to define this behaviour in the API specification, because the client builds against the specification and nothing else. An alternative is versioning in a header, which keeps the URL clean but is harder to see and easier for a client to forget. Whichever approach a bank chooses, it must be consistent across all its APIs, because a client that integrates with five APIs should not have to learn five different versioning schemes. Source: API design guidance from the Berlin Group and the UK Open Banking Implementation Entity; bank API developer documentation. A new version is a new path, not a change to the old one. When the bank releases /v2/payments, /v1/payments keeps working exactly as before, with the same fields, the same validation and the same behaviour. The bank publishes a changelog that lists what changed in v2, a migration guide that tells clients how to move, and a sunset date: the date after which v1 will stop working. The sunset date must be far enough in the future for clients to migrate, typically 12 to 18 months for a payment API, because a corporate client that pays 500 suppliers every Friday cannot rewrite its treasury system in a week. The bank also publishes a deprecation notice: v1 is deprecated, meaning no new features will be added to it, but it continues to work until the sunset date. Breaking changes are the reason versions exist. A breaking change is any change that can cause an existing client to fail: removing a field, renaming a field, changing a field type, making an optional field mandatory, or changing the meaning of a status code. A bank must never make a breaking change inside a version; it must release a new version instead. Non breaking changes, such as adding an optional field or adding a new endpoint, can be made inside a version, because existing clients ignore fields they do not know. The discipline is to ask, for every change, whether a client built against the current version could fail because of it. If the answer is yes, it is a new version. If the answer is no, it can go into the current version, and the changelog says so. Version negotiation is how a client tells the bank which version it wants. With path versioning, the client simply calls the versioned URL. With header versioning, the client sends a header such as Accept-Version: 2. The bank must reject a request that asks for a version that does not exist, with a clear error: 404 for an unknown path version, or 400 with a code such as UNSUPPORTED_VERSION for an unknown header version. The bank must never silently serve a different version from the one the client asked for, because the client would then receive a response it did not expect, and a payment instruction could be misinterpreted. For a business analyst, the requirement is to define the versioning scheme, the deprecation policy, the sunset period, and the error returned for an unknown version, and to write them into the API specification before the first client integrates. Deprecation notices must be specific and honest. A notice that says v1 is deprecated and will be removed on 1 March 2027 tells the client exactly what will happen and when. A notice that says v1 is deprecated and will be removed soon tells the client nothing, and the client will ignore it until the API stops working. The bank should also tell the client what will happen to requests sent to v1 after the sunset date: whether they return a 404, a 410 Gone, or a 400 with a code such as VERSION_RETIRED, and whether the bank will send a warning before the sunset date. A client that discovers the sunset by receiving errors on a Friday afternoon, when it is paying 500 suppliers, is a client that will escalate to the bank's senior management. The deprecation policy is a commercial commitment, not a technical detail, and it belongs in the API terms of service as well as in the developer documentation. The API documentation must state this rule plainly, because a client that has to guess will guess wrong. Internal versioning is different from external versioning. Inside the bank, services change frequently, and internal APIs may version with every release. But the external API, the one clients build against, must change slowly and deliberately, because every change costs every client time and money. A bank that releases a new external version every month is telling its clients that it does not value their integration effort. A bank that never releases a new version is telling its clients that it cannot improve. The right cadence for a payment API is one or two major versions a year, with minor additions inside a version as needed. For a business analyst, the requirement is to define the external version cadence, the deprecation policy, and the communication plan for each new version, and to get the product owner to approve them before the API is published. Further reading: Berlin Group NextGenPSD2 API framework; UK Open Banking API standards. Last reviewed 7 November 2026.