Versioning & stability
Two version numbers apply to every call you make, and they promise different things.
The API is versioned by its /v1 prefix. That is the substantive contract — it says the endpoints, fields and behaviour you build against will not be taken away without notice. It is documented in Versioning & stability, and nothing on this page weakens it.
The package version — the number on @revenexx/sdk or revenexx/sdk — is narrower. It describes the client's own surface: method names, argument shapes, generated types. This page is about that second number.
Today: treat every upgrade as a change you test
The API clients are 0.x, and 0.x means what it conventionally means: the surface is still settling.
Concretely, before a client reaches 1.0:
- A release may still move the client surface. A method can be renamed, an argument can change shape, a generated type can narrow — 0.x is where that is allowed to happen.
- But it cannot reach you in a patch. Every release of the three generated API clients is checked before it is published: the client it would ship is compared, symbol by symbol, with the one the previous release shipped. A difference that could stop your code compiling cannot go out as a patch — it has to arrive as a minor (
0.1.6→0.2.0). So pre-1.0, the minor is the digit that means "read the notes before upgrading". - The check reads shape, not behaviour. It compares methods, arguments, types and enum values. What a call does can still change in a patch, and a new optional argument or field can appear in one. The Changelog remains the place that tells you.
- Pin an exact version in
package.jsonorcomposer.json, and upgrade deliberately rather than on a caret range. A patch is a smaller risk than it was, not no risk.
{
"dependencies": {
"@revenexx/sdk": "<VERSION>"
}
}
{
"require": {
"revenexx/sdk": "<VERSION>"
}
}
That caution is specific to 0.x, and it is also why no page in this portal pins a current version for you. Ask the registry instead: npm view @revenexx/sdk version, or the package page on Packagist.
What changes at 1.0
A client at 1.0 is a promise that the number carries meaning. From that release on, it is ordinary semver, and you can read a diff of version numbers instead of a changelog:
| Bump | What it tells you |
|---|---|
Patch (1.0.0 → 1.0.1) | Fixes only. Nothing you call has changed shape. |
Minor (1.0.0 → 1.1.0) | New methods, new optional arguments, new fields on returned types. Your existing calls compile and behave as before. |
Major (1.0.0 → 2.0.0) | Something you call has changed. Read the migration notes before upgrading. |
That makes ^1.0.0 a safe range to depend on, which is the practical difference 1.0 buys you: you stop reading release notes for fixes and features, and read them only when the major moves.
A 1.0 is about the client, not the API
A client reaching 1.0 does not make the API more stable than it already is, and a client still at 0.x does not make it less so. These are the two easiest things to confuse, so they are worth separating.
The /v1 guarantees are in force today, for every caller, SDK or not:
- Changes within
/v1are additive — new endpoints and optional fields, never a field removed or retyped in place. - A breaking change lands beside the behaviour it replaces and the old one is retired through published stages.
- You get at least four weeks between the announcement and a removal, with a migration path published alongside it.
So if you are weighing whether to build now or wait for a 1.0: the contract you are building against is the API's, and it is already written down. What a 1.0 adds is that your dependency manager can be trusted to respect it too.
How a change reaches you
The Changelog is the channel. Deprecations and breaking changes are announced there before they take effect, for the API and for the packages alike. Subscribe to it rather than polling the registries.
What to do in your project
Three habits that hold before and after 1.0:
- Pin, then upgrade on purpose. An exact pin while the clients are 0.x;
^1.0.0once the client you use has reached 1.0. - Upgrade the typed client with your compiler on, so it tells you what moved instead of a runtime error.
- Read what you use, ignore the rest. New fields appear in responses under
/v1by design. A client that fails on an unknown field is a client that breaks on an additive change.
Which packages this covers
This page covers the generated API clients and the CLI — @revenexx/sdk, @revenexx/node, revenexx/sdk and @revenexx/cli. All four are generated from the same OpenAPI document and follow the policy above.
The surface check described above runs over the three API clients, not the CLI. A command, flag or output shape can therefore still move in a CLI patch, and the CLI's release notes are the only thing that tells you. Everything else on this page applies to all four.
They are not released in lockstep, though, and each carries its own number. One client being a version ahead of another says nothing about either one's surface, and a client reaching 1.0 does not carry its siblings there. Check the version of the package you actually install.
The two platform SDKs version on their own cadence and against their own surfaces, not the API's — see App SDK and Integration Node SDK for where each one stands.
Your own App's version is a third thing again: it is the contract you publish to merchants and to apps that depend on yours. Its rules are stricter than semver's, and they are in App versioning.
Where to go next
- Versioning & stability — the API contract itself: what counts as a break, the retirement stages, and the notice period.
- SDKs — the current status of every client.
- App versioning — versioning an App you publish.
- Changelog — where every change is announced.