Migration
What changed between API versions, with before-and-after code.
The API module carries its own semantic version, separate from the plugin's. Breaking changes require a major bump and never appear in a patch release.
1.0.0
The first release. Nothing to migrate from.
What "breaking" means here
So you know what to expect from future releases:
Breaking, requires a major bump
- Removing or renaming a method, class, enum constant or event field.
- Changing a method's parameters or return type.
- Adding a method to an interface you are expected to implement.
- Narrowing what a method accepts, or widening what it can return to include
null.
Not breaking
- Adding a method to
ZyAuctionsApi, which you consume rather than implement. - Adding an enum constant to a result status — always handle these with a
defaultbranch. - Adding a new event, or a new method to an existing one.
- Changing behaviour behind a documented contract, such as which category a new Minecraft material is filed under.
Result status enums — ListingResult.Status, PurchaseResult.Status,
BidResult.Status, CancelResult.Status — will gain constants over time as new refusal
reasons appear. Always give your switch a default branch. A switch that is exhaustive
today will fail to compile, or throw, on the next minor release otherwise.
switch (result.status()) {
case SUCCESS -> celebrate();
case CANNOT_AFFORD -> tellThemWhy();
default -> generic(result.status());
}Deprecation policy
Anything on its way out is marked before it goes:
@Deprecated(forRemoval = true, since = "2.3.0")It keeps working for at least two minor releases, the Javadoc names what to use instead, and the removal gets its own section on this page with before-and-after code. You will not find a method that simply vanished.
Checking the version at runtime
If you support more than one ZyAuctions release, apiVersion() tells you what you are
talking to:
String version = ZyAuctions.get().apiVersion();
if (!version.startsWith("1.")) {
getSLF4JLogger().warn(
"Built against ZyAuctions API 1.x but found {}; disabling the integration.",
version);
return;
}Compile against the oldest version you intend to support. New methods added in later releases are additive, so a plugin built against 1.0.0 keeps working on 1.4.0 without recompiling.