Start versioning API releases

[matej-g]

We discussed this in the last community meeting, in the context of now having a release process for obsctl (observatorium/obsctl#26).

There were couple of ideas floating around:

• Having versioned releases could encourage higher adoption, i.e. show we're serious about progressing towards stable release
• It would keep us as well accountable for moving towards the stable release aim
• It could force us to be more mindful about what features we're adding and define what we want to have in a stable release
• It could give us easier way to deprecate features (e.g. we still have a /legacy) path: We could indicate this by e.g. saying we'll drop a certain feature in 3 minor releases

To accomplish this we need:

• Agree on versioning (most probably semantic versioning) and the starting version (0.1.0?)
• Have a release process, release schedule

[squat]

Sounds great, I'd love to see Observatorium formalize its development process more.
To add some historical context, the project already published a few releases in semver format up to 0.1.2. Even though the last release was over a year ago and lots of things have changed, we could probably start our next release at 0.2.0, since there are no guarantees of API compatibility for any release below 1.0.0.

[jessicalins]

We have an openapi spec added for metrics and rules/raw - I wonder if it makes sense to expand to the other signals and integrate the api versioning with the specs? Not sure what would be the best practice

[saswatamcode]

Adding log support in openapi spec is planned in #294. Versioning the spec in the same way as the API itself would be nice as people can generate tooling according to versions! :)

[squat]

Versioning the spec in the same way as the API itself would be nice

Hmm I tend to disagree here. The HTTP API is a contract and the version of that contract should only change when the contract changes. By contrast, the version of the binary can change whenever new features are added or removed. E.g. we remove OPA support from the binary, causing the need for a new major release, but the HTTP API stays exactly the same, so this version stays the same. This is also incidentally how Kube does its versioning: all of the APIs (e.g. apps/v1) are versioned independently from Kube releases (e.g. v1.23.0).

[saswatamcode]

That makes sense and is a better approach than what I suggested!
We haven't been maintaining a versioned spec either so that would also be a task.

[squat]

Yes. We also need to think carefully about ensuring that the paths that the HTTP API exposes actually conform to the version of the API contract, e.g. the Rules API is currently set to 0.0.2 [0] but most of our HTTP paths say x/v1/y, whereas here it should probably be x/v0/y.

[0] https://github.com/observatorium/api/blob/main/rules/spec.yaml#L4

[philipgough]

At the risk of going slightly off topic, what are the plans for the legacy metrics endpoints going forward? Does it need to be maintained?

It would be great to have some sort of roadmap for the project and its intentions to get to a stable release going forward.

[matej-g]

@philipgough I guess since we don't really have a stable version yet, we could simply deprecate it and eventually remove it after couple of minor releases 🤷

[squat]

I think that by calling it legacy it is already effectively deprecated, no? I would be in favor of dropping it from main and cutting a new release soon.

[matej-g]

AFAIK no one depends on it, I'm totally fine with dropping it straight away; just if we wanted to be more cautious and do it over the course of couple releases, but it seems it's not necessary.

[jessicalins]

if there are no dependencies to the current legacy endpoints I'd be in favor to dropping it straight away as well :) +1