(Reading the general README is recommended before reading this document).
The Monit24.pl API allows you to manage your Monit24.pl account. This document contains some basic examples of the API usage.
To access your user data, use the User::Read method:
{
"module":"User",
"method":"Read",
"auth":{"login":"monit_api_test_user","password":"my_passwoRd"}
}
A success will look like this:
{
"auth":{},
"version":"2.0.0",
"error":null,
"data":{
"contact_phone":"123456789",
"language":"en",
"contact_person":"John Smith",
"last_login_ip":null,
"last_login_timestamp":null,
"login":"monit_api_test_user",
"email":"test_user@monit24.pl",
"tax_id":null,
"address":null,
"id":4848
}
}
As already mentioned in the general README, you can call this method by sending a HTTP POST request. The above example using cURL:
curl -X POST -i -H "Content-Type: application/json"
-d '{"module":"User","method":"Read","auth":{"login":"monit_api_test_user","password":"my_passwoRd"}}'
https://api.cloudmonit.pl/2.0.0/json_api
Again, remember to set Content-Type header to application/json, otherwise you will get an error.
Before you create a service, you will need to check what service types (http, smtp, ping etc.) are available for your account. You can do this by calling the ServiceType::Find method:
{"module":"ServiceType","method":"Find","auth":{"login":"%[ brand.symbol %]_api_test_user","password":"my_passwoRd"}}
This call will return a list of available types:
{
"auth":{},
"version":"2.0.0",
"error":null,
"data":{
"elements":[
{"name":"http","id":1,"prefix":"http://"},
{"name":"smtp-helo","id":2,"prefix":"smtp://"},
{"name":"https","id":5,"prefix":"https://"},
{"name":"ping","id":7,"prefix":"ping://"}
],
"total":4
}
}
Depending on your account's configuration, different types may be available.
Once we know the available types, we can create a simple service with the Service::Create method. For example, let's create a http service that will check the http://monit24.pl URL every 15 minutes:
{
"module":"Service",
"method":"Create",
"auth":{"login":"monit_api_test_user","password":"my_passwoRd"},
"data":{
"type_id":1,
"url":"monit24.pl",
"interval":900,
"name":"Test service"
}
}
Calling this method will create a new service in your default group (you can change the group by passing a group_id argument). The response will contain the ID of the new service:
{"auth":{},"version":"2.0.0","error":null,"data":{"id":278172}}
These four values (type_id, url, interval and name) are the only required arguments to Service::Create. However, this method supports many other, optional arguments (like the mentioned group_id). Refer to its documentation for more details.
Use the Service::Read method to get information about a service:
{"module":"Service","method":"Read","auth":{"login":"monit_api_test_user","password":"my_passwoRd"},"data":{"id":278172}}
This produces an output similar to this:
{
"auth":{},
"version":"2.0.0",
"error":null,
"data":{
"avg_response_time":173452,
"type_prefix":"http://",
"pause":0,
"type_id":1,
"url":"monit24.pl",
"error":0,
"id":278172,
"last_invalid_check":null,
"suspension":0,
"type_name":"http",
"name":"Test service",
"interval":900,
"description":null,
"silent_mode":0,
"group_id":150505515,
"last_valid_check":1366276740.86716
}
}
The meaning of these information is described in the method's documentation. They include those we have already seen (id, type_id, url, name and interval), some information about the monitoring status (pause, error, ...) and advanced configuration parameters (like the group_id). More fields can be fetched by specifying the with argument to Read.
You can also find information about all your services using the Service::Find method:
{"module":"Service","method":"Find","auth":{"login":"monit_api_test_user","password":"my_passwoRd"}}
The output (after adding another service):
{
"auth":{},
"version":"2.0.0",
"error":null,
"data":{
"elements":[
{
"type_name":"http",
"name":"Test service",
"interval":900,
"pause":0,
"silent_mode":0,
"group_id":150505515,
"type_id":1,
"error":0,
"id":278172,
"last_valid_check":1366277640.84679,
"last_invalid_check":null,
"suspension":0
},
{
"type_name":"http",
"name":"Test service 2",
"interval":1800,
"pause":0,
"silent_mode":0,
"group_id":150505515,
"type_id":1,
"error":0,
"id":278173,
"last_valid_check":1366277942.58508,
"last_invalid_check":null,
"suspension":0
}
],
"total":2
}
}
This is not as verbose as the Service::Read's output for a single service. As a general rule (not only for the Service module), the Find output fields will be a subset of Read output fields. The standard CRUD methods used in API modules (Create, Read, Find, Update and Delete) are described in more detail in CRUD. You can alter this behaviour by specifying the with argument to Read or Find (not all modules support it, refer to the module's documentation for details).
To update a service, use the Service::Update method. For example, to change the description and checks frequency (interval) of the service we created before, we could use:
{
"module":"Service",
"method":"Update",
"auth":{"login":"monit_api_test_user","password":"my_passwoRd"},
"data":{
"id":278172,
"description":"This is my first service!",
"interval":1800
}
}
A special case of updating a service is enabling or disabling the monitoring. To stop or start service monitoring, simply update its pause attribute:
{"module":"Service","method":"Update","auth":{"login":"monit_api_test_user","password":"my_passwoRd"},"data":{"id":278172,"pause":1}}
{"module":"Service","method":"Update","auth":{"login":"monit_api_test_user","password":"my_passwoRd"},"data":{"id":278172,"pause":0}}
To delete a service, use the Service::Delete method:
{"module":"Service","method":"Delete","auth":{"login":"monit_api_test_user","password":"my_passwoRd"},"data":{"id":278172}}
Each account has one or more service groups and each service belongs to exactly one group. The group determines the notification and report addresses and monitoring locations for its services. One of the groups is a special group called the default group. New services will be added to the default group unless specified otherwise. The default group is created when the account is created and cannot be deleted (unless the account is deleted).
Use the Group::Find method to list all your groups or Group::Read to fetch information about a single group (by its ID) An example:
{"module":"Group","method":"Find","auth":{"login":"monit_api_test_user","password":"my_passwoRd"}}
{
"auth":{},
"version":"2.0.0",
"error":null,
"data":{
"elements":[
{
"language":null,
"name":"Default group",
"default":1,
"id":150505515,
"weekly_reports":1,
"daily_reports":1,
"monthly_reports":1,
"account_id":4848
}
],
"total":1
}
}
The default attribute informs if a group is the default group for the account.
When creating a group, you only need to specify its name:
{"module":"Group","method":"Create","auth":{"login":"monit_api_test_user","password":"my_passwoRd"},"data":{"name":"Another group"}}
(when you are a distributor, you also need to specify the account id)
You can also specify other settings (language, location_ids, daily_reports, weekly_reports and monthly_reports) if you don't find the defaults suitable.
By default, new services will be added to your default group. You can change this by passing the group_id parameter to Service::Create. You can move services from one group to another by updating their group_id attribute.
The NotificationAddress and ReportAddress modules provide standard CRUD operations on addresses. Keep in mind that each address is assigned to a group, so if you want to be informed about events regarding services in more than one group you will have to create one such object for each group.
You can change the monitoring locations for a group by updating its location_ids attribute (it's an array of the location identifiers). To list available locations, use the Location::Find method. Each service in a group is monitored from the same locations.
Each account has certain limits of what it can do. (internally these limits are defined in something called a "package"). You can check your limits using the Package module or by using Account::Read with "limits" and "service_types":. Below is a sample input and output of these methods:
{
"module":"Account",
"method":"Read",
"auth":{"login":"monit_api_test_user","password":"my_passwoRd"},
"with":["limits","service_types"]
}
{
"auth":{},
"version":"2.0.0",
"error":null,
"data":{
"activated":1,
"blocked":0,
"name":"demo_account",
"id":4848,
"min_locations_limit":2,
"min_interval":900,
"notification_channels":["email_extended","email_long","email_short","gadu_gadu","jabber"],
"package_id":632,
"max_locations_limit":3,
"max_services":3,
"service_types":[
{"min_interval":900,"name":"http","id":1,"max_services":3},
{"min_interval":900,"name":"smtp-helo","id":2,"max_services":3},
{"min_interval":1800,"name":"https","id":5,"max_services":1},
{"min_interval":900,"name":"ping","id":7,"max_services":3}
]
}
}
The above mean that:
email_extended, email_long, email_short, gadu_gadu and jabber channels (so you are not allowed to use SMS notifications)https service, and it cannot be checked more frequently than once every 1800 seconds (30 minutes)The limits can be changed by the Monit24.pl administrators.