API Versioning

[diwakergupta]

Two separate things to discuss here:

1. Versioning scheme for the API itself: we're following SemVer but we're still at major number 0. We need to decide when it makes sense to do a 1.0.0 release, at which point we can leverage the major number to communicate breaking upgrades.
2. Capturing/enforcing dependency on Stacks Blockchain: due to the strong coupling between the event dispatcher and the API, a correctly working API instance imposes some constraints on which stacks-node versions it is compatible with. Usually, this is an upper bound on the supported stacks-blockchain version (e.g. API version 0.55.3 only supports stacks-blockchain upto 2.0.x). This information should be captured somewhere and ideally enforced in the API.

Thoughts?

[zone117x]

a correctly working API instance imposes some constraints on which stacks-node versions it is compatible with. Usually, this is an upper bound on the supported stacks-blockchain version (e.g. API version 0.55.3 only supports stacks-blockchain upto 2.0.x).

Here's some options:

A. Hardcode the stacks-node version range within the API repo, with the known compatible range, and manually update them. This could be enforced during the API runtime, like during startup where it already queries the /v2/info endpoint. This is essentially using the same manual process we are already doing in our own deployments, but making the versions more visible somehow, and providing early, useful error messages when incompatible versions are deployed. The downside is no semver usage, and can be error prone due to the stacks-node + API version compatibility being mostly an afterthought.

B. Include sidecar-compatibility in the stacks-node semver, and match the API to it. This seems like the worst option IMO. The stacks-node can have major version bumps that are unrelated to sidecar functionality (as is the current case) which forces unnecessary bumps+releases in the API. Additionally, if the stacks-node must perform a major version bump only for sidecar related changes, it could confuse node operators/miners who aren't running the API.

C. Add a new version field in the stacks-node that only represents sidecar semver compatibility. This version number could be added to the /v2/info endpoint, and the API could perform the same check described in option A, but it would be more accurate and less frequent updates required due to semver.

Thoughts?

[lgalabru]

I think I'd be in favor of option A.
Note that if we're updating the API repo for every single new release of the stacks-node (to update the compatibility matrix), then we could just use the same version that the stacks-node is using, and add one last component (2.0.10.1.3 on the stacks node side, and 2.0.10.1.3.0 on the api side).
I think this approach could be slightly less convenient for us as maintainers (we'd have to bump the api version when we release a new stacks-node, even if no changes on the sidecar side), but it would be crystal clear for the rest of the world.

[kantai]

I agree -- Option A is the best for now and we can probably create a not-too-complex GH action that opened a PR on stacks-blockchain-api every time a release was created on the stacks-blockchain repo.

Option C could be better long term-- we may be able to version an OpenAPI spec for the sidecar to achieve that, and then there's at least some versioning that the sidecar could take advantage of.

[zone117x]

@CharlieC3 thoughts? @lgalabru's suggestion would change how we currently do automatic versioning/deployments in this repo.

[zone117x]

Ping. @wileyj too

[CharlieC3]

Thoughts on each option:

Option A: I like this option. If we follow semantic versioning in the stacks-blockchain as described here, we should be able to define compatibility ranges for the API to the stacks-node similar to how we specify library dependencies in a package.json or cargo.toml file. e.g. ^2.0.11.2.0 would translate to 2.0.11.x.x.

Option B: This option offers the smallest amount of flexibility and will feel very constricting. It will likely force us to make bumps in the API which wouldn't make sense.

Option C: I think if we implement Option A and do our best to follow semver rule linked out above in the stacks-blockchain repo, this option would be redundant. It also seems like with this option the dependee is defining a compatibility range up stream.

The API cannot run without a stacks-node, but the stacks-node is able to run without an API. This flow can dictate which service defines the compatibility range. So in this case, the API would define the stacks-node version range it's compatible with -- e.g. API 0.62.0 -> stacks-node 2.0.11.x.x.

[zone117x]

This issue was recently brought up in regards to the Rosetta dockerfile versioning #563 (comment)