See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-1038

From Zabbix.org
Jump to: navigation, search

Version for API, API methods and API classes

ZBXNEXT-1038

Status: Draft

Description

Summary

Now API has version, but it's hardly ever updated and trunk API version is lower than the version for 1.8. Additionally, users might want to use only a few specific calls, and they wouldn't care if another method has been changed - currently they can not determine which methods have changed.

Specification

Every API method should have separate version, incremented when method functionality is changed. Class versions and API version will be calculated from method versions.

Details

Numbering

API version number on any level consists of two parts, written as x.y.

  • First number is changed when any existing functionality is changed in any way.
  • Second number is changed when some new functionality is added, but everything existing works exactly the same.
  • These numbers do not form a decimal number, they are treated like software versions, for example. Thus 1.13 > 1.9.
What if one API method calls a different method, and the method, that's being called is updated, should the client methods version be incremented as well? Jelisejev 09:23, 19 March 2012 (SAST)
only if the "depending" api method changes from the user perspective. if the called method changes, but the methods that call it have no changes whatsoever, their versions stay as is --Richlv 11:04, 19 March 2012 (SAST)

Calculated versions

  • Class version calculation formula: sum of all methods versions of this class.
  • API version calculation formula: sum of all classes versions.
  • When summing, both parts are calculated separately. For example, two methods with versions 1.7 and 3.8 would result in the class version of 4.13.

Adding and removing methods and classes

  • Adding new method always starts with first number as "0".
    • This ensures that first number of the class does not change when adding new functionality (as the first number denoted compatibility breaking changes).
  • It is also possible to specify version on a class and global level. This version is used in addition to the calculated class or global version. It starts at 0.0 and is used when a method or class is removed. When a method is removed, class version is increased by x+1.y, were x.y is the last version this method had. When a class is removed, global API version is increased with the last version for that class in the same way.
    • This ensures that calculated API versions never decrease.


  • If a request for a version of non-existent method or class is received, response should clearly indicate that and have a unique error code.

API changes

  • APIInfo.version method will be able to receive additional parameter: array of class or class.method names and return hash of input names as keys and versions as value.

Input example:

["Host", "Map.get", "Map.create", "Item"]

Output Example:

{"Host": 12.2, "Map.get": 3.7, "Map.create": 5.1, "Item": 22.0}
  • If APIInfo.version is called without parameters global API version is returned.

Comments

nelsonab

API versioning by method alone I do not believe to be a good idea. In the above format it would not be possible to determine upon connection to Zabbix what API version/level one is working with. If there was a master call for the overall API version which was updated in a consistent and appropriate manner then the above method would be suitable as a meta information method. For instance you could use the API version per-method call to determine what was the last "API Version" where this method was updated. In addition independent counters per API Method may be too granular, and may be too complex to properly maintain.