I'd like to weigh in on this one. I'm commenting in the tracker rather than the wiki page because I'm trying to impart a sense of urgency rather than give my technical opinion.

I wrote a simple Perl module (for $work, but it got open-sourced/freed) to abstract away some details of the Zabbix API and, regarding the API version, two things came up most often:

• Users would try to use the API (either through my module or with raw JSON queries) and would meet different errors (or no errors, or no errors but it wouldn't work) depending on their version of Zabbix. Having a different API version number would have accurately conveyed the information that "this bug exists in version $FOO and has been fixed in version $BAR, you can upgrade to any version of Zabbix $BAZ or more". As it is I usually answered "I really don't know, go ask on their IRC channel/forum".

• As a developer: my module targets the 1.8.x series and I test against 1.8.5 and 1.8.11 (since that's what we use at $work). Both versions have different bugs (e.g. my module can create triggers in 1.8.11, it can't in 1.8.5). The unit tests need to know what tests can be run depending on the API version: creating triggers is not a feature of Zabbix 1.8.11, creating triggers via the API is. But both Zabbixen report their API version as 1.3.

My point is that this feature needs to be introduced as soon as possible, or it just increases the amount of similarly-numbered-yet-slightly-different API versions. Either a global x.y.z version or API class/method versions work for me, honestly.

The documentation for the 1.8.x series could use an update as well. Right now it's showing user.authenticate being introduced for "1.8", and deprecated. But user.login has also been introduced for "1.8"! I can't write a module that knows to call authenticate for such and such version and login for later versions because the information is not available. Alternatively, the Zabbix version could be made available through the API.

I realize you'd prefer to support only the most recent 2.x Zabbix (backporting fixes is a pain), but right now enterprise installations will be largely 1.8.x since that's what on Debian stable and testing, Ubuntu LTS and latest Fedora (so probably RHEL and CentOS too).