Zabbix Documentation 4.2

3.04.04.4 (current)| In development:5.0 (devel)| Unsupported:1.82.02.22.43.23.44.2Guidelines

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 [2014/09/30 12:54]
127.0.0.1 external edit
manual:api [2019/01/28 14:51]
sasha <code js> => <code java>
Line 1: Line 1:
-===== 17. API ===== 
  
-==== Overview ==== 
- 
-Zabbix API allows you to programmatically retrieve and modify the configuration of Zabbix and provides access to historical data. It is widely used to: 
-  * Create new applications to work with Zabbix; 
-  * Integrate Zabbix with third party software; 
-  * Automate routine tasks. 
- 
-The Zabbix API is a web based API and is shipped as part of the web frontend. It uses the JSON-RPC 2.0 protocol which means two things: 
-  * The API consists of a set of separate methods; 
-  * Requests and responses between the clients and the API are encoded using the JSON format. 
- 
-More info about the protocol and JSON can be found in the [[http://​www.jsonrpc.org/​specification|JSON-RPC 2.0 specification]] and the [[http://​json.org/​|JSON format homepage]]. 
- 
-==== Structure ==== 
- 
-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>​ 
- 
-==== Performing requests ==== 
- 
-Once you've set up the frontend, you can use remote HTTP requests to call the API. To do that you need to send HTTP POST requests to the ''​api_jsonrpc.php''​ file located in the frontend directory. For example, if your Zabbix frontend is installed under //​%%http://​company.com/​zabbix%%//,​ the HTTP request to call the ''​apiinfo.version''​ method may look like this: 
-<code http> 
-POST http://​company.com/​zabbix/​api_jsonrpc.php HTTP/1.1 
-Content-Type:​ application/​json-rpc 
- 
-{"​jsonrpc":"​2.0","​method":"​apiinfo.version","​id":​1,"​auth":​null,"​params":​{}} 
-</​code>​ 
- 
-The request must have the ''​Content-Type''​ header set to one of these values: ''​application/​json-rpc'',​ ''​application/​json''​ or ''​application/​jsonrequest''​. 
- 
-<note tip>You can use any HTTP client or a JSON-RPC testing tool to perform API requests manually, but for developing applications we suggest you use one of the [[http://​zabbix.org/​wiki/​Docs/​api/​libraries|community maintained libraries]].</​note>​ 
- 
-==== Example workflow ==== 
- 
-The following section will walk you through some usage examples in more detail. 
- 
-=== Authentication === 
- 
-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> 
-{ 
-    "​jsonrpc":​ "​2.0",​ 
-    "​method":​ "​user.login",​ 
-    "​params":​ { 
-        "​user":​ "​Admin",​ 
-        "​password":​ "​zabbix"​ 
-    }, 
-    "​id":​ 1, 
-    "​auth":​ null 
-} 
-</​code> ​ 
- 
-Let's take a closer look at the request object. It has the following properties: 
-  * ''​jsonrpc''​ - the version of the JSON-RPC protocol used by the API; the Zabbix API implements JSON-RPC version 2.0; 
-  * ''​method''​ - the API method being called; 
-  * ''​params''​ - parameters that will be passed to the API method; 
-  * ''​id''​ - an arbitrary identifier of the request; 
-  * ''​auth''​ - a user authentication token; since we don't have one yet, it's set to ''​null''​. 
- 
-If you provided the credentials correctly, the response returned by the API will contain the user authentication token: 
- 
-<code js> 
-{ 
-    "​jsonrpc":​ "​2.0",​ 
-    "​result":​ "​0424bd59b807674191e7d77572075f33",​ 
-    "​id":​ 1 
-} 
-</​code>​ 
- 
-The response object in turn contains the following properties: 
-  * ''​jsonrpc''​ - again, the version of the JSON-RPC protocol; 
-  * ''​result''​ - the data returned by the method; 
-  * ''​id''​ - identifier of the corresponding request. 
- 
-=== Retrieving 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> 
-{ 
-    "​jsonrpc":​ "​2.0",​ 
-    "​method":​ "​host.get",​ 
-    "​params":​ { 
-        "​output":​ [ 
-            "​hostid",​ 
-            "​host"​ 
-        ], 
-        "​selectInterfaces":​ [ 
-            "​interfaceid",​ 
-            "​ip"​ 
-        ] 
-    }, 
-    "​id":​ 2, 
-    "​auth":​ "​0424bd59b807674191e7d77572075f33"​ 
-} 
-</​code>​ 
- 
-<note important>​Note that the ''​auth''​ property is now set to the authentication token we've obtained by calling ''​user.login''​.</​note>​ 
- 
-The response object will contain the requested data about the hosts: 
-<code js> 
-{ 
-    "​jsonrpc":​ "​2.0",​ 
-    "​result":​ [ 
-        { 
-            "​hostid":​ "​10084",​ 
-            "​host":​ "​Zabbix server",​ 
-            "​interfaces":​ [ 
-                { 
-                    "​interfaceid":​ "​1",​ 
-                    "​ip":​ "​127.0.0.1"​ 
-                } 
-            ] 
-        } 
-    ], 
-    "​id":​ 2 
-} 
-</​code>​ 
- 
-<note tip>For performance reasons we recommend to always list the object properties you want to retrieve and avoid retrieving everything.</​note>​ 
- 
-=== Creating a new item === 
- 
-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> 
-{ 
-    "​jsonrpc":​ "​2.0",​ 
-    "​method":​ "​item.create",​ 
-    "​params":​ { 
-        "​name":​ "Free disk space on $1", 
-        "​key_":​ "​vfs.fs.size[/​home/​joe/,​free]",​ 
-        "​hostid":​ "​10084",​ 
-        "​type":​ 0, 
-        "​value_type":​ 3, 
-        "​interfaceid":​ "​1",​ 
-        "​delay":​ 30 
-    }, 
-    "​auth":​ "​0424bd59b807674191e7d77572075f33",​ 
-    "​id":​ 3 
-} 
-</​code>​ 
- 
-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> 
-{ 
-    "​jsonrpc":​ "​2.0",​ 
-    "​result":​ { 
-        "​itemids":​ [ 
-            "​24759"​ 
-        ] 
-    }, 
-    "​id":​ 3 
-} 
-</​code>​ 
- 
-<note tip>The ''​item.create''​ method as well as other create methods can also accept arrays of objects and create multiple items with one API call.</​note>​ 
-=== Error handling === 
- 
-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> 
-{ 
-    "​jsonrpc":​ "​2.0",​ 
-    "​method":​ "​host.create",​ 
-    "​params":​ { 
-        "​host":​ "Linux server",​ 
-        "​interfaces":​ [ 
-            { 
-                "​type":​ 1, 
-                "​main":​ 1, 
-                "​useip":​ 1, 
-                "​ip":​ "​192.168.3.1",​ 
-                "​dns":​ "",​ 
-                "​port":​ "​10050"​ 
-            } 
-        ] 
-    }, 
-    "​id":​ 3, 
-    "​auth":​ "​0424bd59b807674191e7d77572075f33"​ 
-} 
-</​code>​ 
- 
-The response will then contain an error message: 
- 
-<code js> 
-{ 
-    "​jsonrpc":​ "​2.0",​ 
-    "​error":​ { 
-        "​code":​ -32602, 
-        "​message":​ "​Invalid params.",​ 
-        "​data":​ "No groups for host \"​Linux server\"​."​ 
-    }, 
-    "​id":​ 3 
-} 
-</​code>​ 
- 
-If an error occurred, instead of the ''​result''​ property, the response object will contain an ''​error''​ property with the following data: 
-  * ''​code''​ - an error code; 
-  * ''​message''​ - a short error summary; 
-  * ''​data''​ - a more detailed error message. 
- 
-Errors can occur in different cases, such as, using incorrect input values, a session timeout or trying to access unexisting objects. Your application should be able to gracefully handle these kinds of errors. 
- 
-==== API versions ==== 
- 
-To simplify API versioning, starting from 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. 
- 
-<note tip>You can follow all of the changes made to the API in the [[manual:​api:​changes_2.2_-_2.4|API changelog]].</​note>​ 
-==== 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]].