All posts
Architecture · 10 min read · Jun 4, 2026

Versioning APIs in OSGi-based applications

Versioning APIs in OSGi-based applications

API versioning in OSGi is stricter and more precise than in a typical Java application, because OSGi versions individual exported packages rather than whole artifacts. Semantic versioning is not a convention here; it is enforced by the framework when resolving which bundle satisfies which import. Understanding that model is what lets a large modular system evolve without breaking its consumers.

Packages are the unit of versioning

A bundle can export many packages, each with its own version. Consumers import specific packages within a version range, so the framework can wire a consumer to any provider whose package version falls in that range. This is why a thoughtful package layout matters: an API package and its implementation should never share the same exported package.

Semantic versioning, OSGi style

OSGi assigns clear meaning to each part of a version, and the meaning differs depending on whether you consume or implement the API. The rules are precise:

ChangeVersion bumpEffect on consumers
Add a method to an interfaceMinor (1.1.0)Safe for callers, breaks implementers
Remove or change a methodMajor (2.0.0)Breaking for everyone
Fix a bug, no signature changeMicro (1.0.1)Transparent
Add a new interfaceMinor (1.1.0)Safe for everyone
A change that is safe for API callers can still break implementers, which is why the ranges differ.

Import ranges encode the contract

Because callers and implementers tolerate different changes, they import an API with different version ranges. The framework uses these ranges to refuse an incompatible wiring rather than failing mysteriously at runtime.

java
// A consumer of the API tolerates minor additions:
//   [1.0,2.0)  -> any 1.x is acceptable

// An implementer of the API is stricter:
//   [1.0,1.1)  -> only this minor version is safe

// package-info.java drives the exported version
@org.osgi.annotation.versioning.Version("1.1.0")
package com.example.billing.api;
Consumer and provider ranges differ because they tolerate different kinds of change.

Let the tooling enforce it

The good news is you should not compute these versions by hand. Tools like bnd (built into Liferay's Gradle plugins) compare each build against the previous baseline and fail the build if a change is not reflected in a correct version bump. Treating that baseline check as a required gate turns API versioning from a discipline people forget into a guarantee the build enforces.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar