Zabbix Documentation 4.4

2.23.04.04.2 (current)In development:4.4 (devel)Unsupported:1.82.02.43.23.4

User Tools

Site Tools


manual:api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:api [2016/11/29 12:58]
sasha Links to manual:api:reference:apiinfo:version changed to playground:playground:howtos:api:reference:apiinfo:version
manual:api [2019/04/02 06:04] (current)
Line 18: Line 18:
 The API consists of a number of methods that are nominally grouped into separate APIs. Each of the methods performs one specific task. For example, the ''​host.create''​ method belongs to the //host// API and is used to create new hosts. Historically,​ APIs are sometimes referred to as "​classes"​. The API consists of a number of methods that are nominally grouped into separate APIs. Each of the methods performs one specific task. For example, the ''​host.create''​ method belongs to the //host// API and is used to create new hosts. Historically,​ APIs are sometimes referred to as "​classes"​.
  
-<note tip>Most APIs contain at least four methods: ''​get'',​ ''​create'',​ ''​update''​ and ''​delete''​ for retrieving, creating, updating and deleting data respectfully, but some of the APIs may provide a totally different set of methods.</​note>​+<note tip>Most APIs contain at least four methods: ''​get'',​ ''​create'',​ ''​update''​ and ''​delete''​ for retrieving, creating, updating and deleting data respectively, but some of the APIs may provide a totally different set of methods.</​note>​
  
 ==== Performing requests ==== ==== Performing requests ====
Line 42: Line 42:
 Before you can access any data inside of Zabbix you'll need to log in and obtain an authentication token. This can be done using the ''​[[manual:​api:​reference:​user:​login|user.login]]''​ method. Let us suppose that you want to log in as a standard Zabbix Admin user. Then your JSON request will look like this: Before you can access any data inside of Zabbix you'll need to log in and obtain an authentication token. This can be done using the ''​[[manual:​api:​reference:​user:​login|user.login]]''​ method. Let us suppose that you want to log in as a standard Zabbix Admin user. Then your JSON request will look like this:
  
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 64: Line 64:
 If you provided the credentials correctly, the response returned by the API will contain the user authentication token: If you provided the credentials correctly, the response returned by the API will contain the user authentication token:
  
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 81: Line 81:
 We now have a valid user authentication token that can be used to access the data in Zabbix. For example, let's use the ''​[[manual:​api:​reference:​host:​get|host.get]]''​ method to retrieve the IDs, host names and interfaces of all configured [[manual:​api:​reference:​host:​object|hosts]]:​ We now have a valid user authentication token that can be used to access the data in Zabbix. For example, let's use the ''​[[manual:​api:​reference:​host:​get|host.get]]''​ method to retrieve the IDs, host names and interfaces of all configured [[manual:​api:​reference:​host:​object|hosts]]:​
  
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 103: Line 103:
  
 The response object will contain the requested data about the hosts: The response object will contain the requested data about the hosts:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 128: Line 128:
 Let's create a new [[manual:​api:​reference:​item:​object|item]] on "​Zabbix server"​ using the data we've obtained from the previous ''​host.get''​ request. This can be done by using the ''​[[manual:​api:​reference:​item:​create|item.create]]''​ method: Let's create a new [[manual:​api:​reference:​item:​object|item]] on "​Zabbix server"​ using the data we've obtained from the previous ''​host.get''​ request. This can be done by using the ''​[[manual:​api:​reference:​item:​create|item.create]]''​ method:
  
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 148: Line 148:
 A successful response will contain the ID of the newly created item, which can be used to reference the item in the following requests: A successful response will contain the ID of the newly created item, which can be used to reference the item in the following requests:
  
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 166: Line 166:
 So if create methods accept arrays, we can add multiple [[manual:​api:​reference:​trigger:​object|triggers]] like so: So if create methods accept arrays, we can add multiple [[manual:​api:​reference:​trigger:​object|triggers]] like so:
  
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 186: Line 186:
  
 A successful response will contain the IDs of the newly created triggers: A successful response will contain the IDs of the newly created triggers:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 203: Line 203:
 Enable an item, that is, set its status to "​0":​ Enable an item, that is, set its status to "​0":​
  
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 217: Line 217:
  
 A successful response will contain the ID of the updated item: A successful response will contain the ID of the updated item:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 234: Line 234:
  
 Enable multiple triggers, that is, set their status to 0: Enable multiple triggers, that is, set their status to 0:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 254: Line 254:
  
 A successful response will contain the IDs of the updated triggers: A successful response will contain the IDs of the updated triggers:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 273: Line 273:
 Up to that point everything we've tried has worked fine. But what happens if we try to make an incorrect call to the API? Let's try to create another host by calling ''​[[manual:​api:​reference:​host:​create|host.create]]''​ but omitting the mandatory ''​groups''​ parameter. ​ Up to that point everything we've tried has worked fine. But what happens if we try to make an incorrect call to the API? Let's try to create another host by calling ''​[[manual:​api:​reference:​host:​create|host.create]]''​ but omitting the mandatory ''​groups''​ parameter. ​
  
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 297: Line 297:
 The response will then contain an error message: The response will then contain an error message:
  
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 318: Line 318:
 ==== API versions ==== ==== API versions ====
  
-To simplify API versioning, since Zabbix 2.0.4, the version of the API matches the version of Zabbix itself. You can use the ''​[[playground:​playground:​howtos:​api:​reference:​apiinfo:​version|apiinfo.version]]''​ method to find out the version of the API you're working with. This can be useful for adjusting your application to use version-specific features.+To simplify API versioning, since Zabbix 2.0.4, the version of the API matches the version of Zabbix itself. You can use the ''​[[manual:​api:​reference:​apiinfo:​version|apiinfo.version]]''​ method to find out the version of the API you're working with. This can be useful for adjusting your application to use version-specific features.
  
 We guarantee feature backward compatibility inside of a major version. When making backward incompatible changes between major releases, we usually leave the old features as deprecated in the next release, and only remove them in the release after that. Occasionally,​ we may remove features between major releases without providing any backward compatibility. It is important that you never rely on any deprecated features and migrate to newer alternatives as soon as possible. We guarantee feature backward compatibility inside of a major version. When making backward incompatible changes between major releases, we usually leave the old features as deprecated in the next release, and only remove them in the release after that. Occasionally,​ we may remove features between major releases without providing any backward compatibility. It is important that you never rely on any deprecated features and migrate to newer alternatives as soon as possible.
  
-<note tip>You can follow all of the changes made to the API in the [[manual/​api/​changes_2.4_-_3.0|API changelog]].</​note>​+<note tip>You can follow all of the changes made to the API in the [[manual/​api/​changes_3.4_-_4.0|API changelog]].</​note>​
 ==== Further reading ==== ==== Further reading ====
  
 You now know enough to start working with the Zabbix API, but don't stop here. For further reading we suggest you have a look at the [[manual:​api:​reference|list of available APIs]]. You now know enough to start working with the Zabbix API, but don't stop here. For further reading we suggest you have a look at the [[manual:​api:​reference|list of available APIs]].
 +