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:
| Change | Version bump | Effect on consumers |
|---|---|---|
| Add a method to an interface | Minor (1.1.0) | Safe for callers, breaks implementers |
| Remove or change a method | Major (2.0.0) | Breaking for everyone |
| Fix a bug, no signature change | Micro (1.0.1) | Transparent |
| Add a new interface | Minor (1.1.0) | Safe for everyone |
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.
// 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;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.