Why API Version and Product Version Are Not the Same Thing

In a more complex system, the word "version" quickly stops meaning just one thing.

There may be a version of the application itself. Separately, there may be a public API version. There may also be an integration protocol version or a data schema version.

It is tempting to use one number for everything. For example, if the product is version 3.4.0, perhaps the API should somehow be "version 3" too.

But those numbers answer different questions.

When designing integrations, I use a simple rule: if two versions can change independently, they represent different version dimensions.

These four numbers do not conflict with one another.

They describe different parts of the system:

• the application version identifies a software release;
• the API version identifies an external client contract;
• the protocol version identifies rules of interaction between participants;
• the schema version identifies the structure of a particular data set.

A new application release does not automatically require a new API version. A new data format also does not automatically require a new major API version.

The application version is normally connected to releases of the software itself.

A new release may contain:

• internal refactoring;
• bug fixes;
• new capabilities;
• UI changes;
• dependency upgrades.

The external API contract may remain completely unchanged.

For example, versions 4.8.2 and 4.9.0 may use completely different internal implementations while exposing exactly the same request and response fields.

An API version does not exist to expose the current application release number.

It exists to manage compatibility for external consumers.

When a client uses a particular major API version, it expects the documented rules of that contract to remain valid.

Without breaking that contract, I may:

• fix an internal bug;
• optimize a database query;
• move logic between classes;
• upgrade Laravel;
• change caching implementation.

None of these changes alone requires a new major API version.

Sometimes another layer exists on top of the HTTP API: an interaction protocol between two systems.

It may define:

• the sequence of steps;
• required participant capabilities;
• the meaning of particular messages;
• retry behavior;
• compatibility rules.

This protocol may evolve independently from the HTTP API.

I therefore do not use the API version as an automatic answer to the question of which protocol version a client supports.

There is another compatibility dimension: the structure of data being stored, transferred, or imported.

That format may have its own schemaVersion.

This is especially useful when one API version needs to accept or read several generations of a particular data structure.

The schema can then evolve without forcing an artificial version change for the whole API.

If every version is forced to use the same number, a change in one area starts dragging all the others with it.

The internal product release changes and suddenly the API seems to need a new number. One document schema changes and the protocol appears to require another version too.

This creates coupling where no real dependency exists.

Independent versioning lets me change only the contract that actually changed.

Another boundary I keep separate is deployment versus contract versioning.

A system may be deployed dozens of times while the external API remains on the same version.

That is completely normal.

A new API version is needed not because a new release exists, but because the external agreement changes in a way that makes the previous client contract no longer safely compatible.

For me, the question of a new API version starts with compatibility, not the application release number.

I look at whether the documented external contract changes:

• a required request field;
• response shape;
• the meaning of an existing field;
• operation behavior;
• status or error semantics;
• a rule that external consumers are allowed to rely on.

If the change remains backward compatible, a new major API version may not be necessary at all.

This check helps me notice when version dimensions have been mixed together.

If I cannot explain briefly what a particular version number identifies, the version boundary is probably not clear enough.

And if one number is being used to answer two different compatibility questions, I check whether independent contracts have been coupled accidentally.

An external client normally does not need to know every internal application release number.

It needs to know the versions that affect compatibility of its own integration.

If the client uses API v2 and that contract remains compatible, the internal product may go through many later releases without requiring any client-side change.

This is one reason why a stable external contract should be separated from the pace of internal development.

Before introducing another version number, I ask several questions:

• What exactly is being versioned?
• Which compatibility boundary does this version protect?
• Who needs to know this version?
• Can it change independently from the application version?
• Am I already using another version number for a completely different contract?
• Is the change actually incompatible, or is this simply another software release?

These questions often prevent the introduction of a version number that does not actually have a clear meaning.

My main principle here is simple: I do not try to synchronize version numbers that describe different things.

The product may receive another release without changing the API.

The protocol may evolve independently from the application version.

A particular data structure may have its own schema version.

And as long as the external API remains compatible with its documented contract, its major version should not change merely because another internal release happened.

For me, good versioning starts not with choosing a number, but with identifying the compatibility boundary that number represents.