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:
- Any release may move the client surface. A method can be renamed, an argument can change shape, a generated type can narrow.
- The number itself is not the signal. Don't infer from
0.1.0→0.1.1that nothing you call has moved. Read the release notes. - Pin an exact version in
package.jsonorcomposer.json, and upgrade deliberately rather than on a caret range.
{
"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. - Regenerate your types when you upgrade, so the compiler tells you what moved instead of a runtime error. The CLI generates them from your tenant's own OpenAPI document — see Type generation.
- 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.
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.