When will the API be "stable"?

[shamoon]

I truly ask this question without disrespect or snark or anything like that. I am merely another dev in the FOSS world and have deep understanding of the challenges and joys of maintaining a project. My bias is that having a small integration with Immich has given me the impression that the Immich API is treated with minimal concern about versioning / breaking changes etc. Today's release, for example, makes a purely semantic change and my request to have the old endpoint maintained wasn't really answered.

So, I appreciate that the README states "Expect bugs and breaking changes." but at this point there have been 209 releases in about ~2.75 years, so the question stands, do you guys plan have a plan to start maintaining backwards compatibility / versioning for the API, and if so when?

Thanks for your time

[jrasm91]

FWIW the old endpoints were deprecated like 3 months ago. I think the main issue is that the communication around non-user facing deprecated/breaking changes has not been communicated very well. We can definitely improve this.

We recently added a new label changelog:deprecated that we plan to use going forward to surface these types of changes in a more transparent manner. In general, deprecated changes stick around for several versions before they are removed in a breaking-change release.

[shamoon]

Thanks for your reply.

Sure, communication about breaking changes is one thing, but I’m not sure that’s really the point. The question is why break things that don’t need to be broken at all, or more specifically why not make changes backwards-compatible?

In other words, since the API is public, is there a timeline for when we should expect it to be maintained in a more collaborative way?

[bo0tzz]

We're hoping to hit a stable release early next year. That'll be Immich 2.0.0, and from then on we'll be doing proper semver and way less breaking changes.

[jrasm91]

why break things that don’t need to be broken at all

To be fair that's completely subjective. IMHO things that are accurately named are easier to read, maintain, and consume. The goal is maximizing those things while we are not stable. So I'll agree to disagree that there was no need to break it.

[shamoon]

Yes, agree that is subjective and in no way my call. I meant the decision to remove any form of e.g. redirect which would effectively keep the change non-breaking.

That'll be Immich 2.0.0, and from then on we'll be doing proper semver and way less breaking changes.

Cool, sounds like a plan.

Thanks for engaging everyone, congrats on the successful project.

[jrasm91]

Yeah I think we plan to do this much more aggressively after we are officially stable. At the moment there is just too much stuff that is constantly changing and we believe the technical burden would quickly become overwhelming.