Hi devs,
I’m under the impression that the APIv2 is considered to be stable, e.g. we won’t introduce any backward incompatible changes.
I consider the search parameters to be part of the API, e.g. I don’t feel comfortable changing any search parameters while trying to keep the promise of a stable API.
What do others think about that?
Timo
I personally don’t see search terms we provide as part of an API. I think search syntax is, the grammar, or operators if you will, should be compatible. The list of terminals (keywords) can change. Of course we don’t change it every now and then and try to keep it backwards compatible, but there are cases, where we e.g. need to limit implicit list of attributes to search in (aka google like experience) because it’s just too slow. Or we need to rename some search field, or some fields are lost because now the feature is implemented differently.
I think the elephant in the room is that we have set a compatibility framework but we haven’t really started using it. It is simply too much work to start maintaining V3, V4 and V5 versions of the same controllers. That’s a lot of code either copied or too complex (monkey patching or overriding methods).
Honestly, I think this plan was doomed on delivery. We should not promise what we can’t do. We don’t even have any kind of API compatibility tests in core test suite, Red Hat QA does a good job of covering most of the major usecases tho so at least we know what changed in advance.
I wish I could say API do change, get used to it. If you can’t afford upgrading, then don’t upgrade. But, let me say this: this would only work if we are able to present API changes to users in a nice way, preferably via some auto-generated way and diff. Then it would not be such a burden to update scripts and integration. Today, we basically say “API v2 should be compatible” but it’s not really. And no documentation showing what exactly changed either.
We do maintain status quo. The problem is - it is a challenge. We do have a nice API docs generator with auto-generated examples and it’s a solid base worth elaborating.
Coming from a developer’s perspective API changes are really a pain in the *** most of the time.
Because of the chain of tools involved I would be careful with major changes. Every now and then it would make sense to upgrade the API to a new major version and drop support of the oldest.
In my experience only two versions of an API should be active to minimize developing effort. If a new version is really needed, users have enough time to update their own tools because the current version is still working. Users jumping from v1 to v3 can’t be helped imho.