SDK

Monitis provides Java, PHP and Bash SDKs to help you use REST API.

Java SDK - Documentation | Download | Examples

Bash-Custom-SDK - Documentation | Download

PHP SDK - Documentation | Download | Examples

There are also pretty much scripts on the Github which are supported by the community.

Authentication and Validation

To authenticate requests to Monitis API first of all you need to get an apikey and secretkey. You can get those keys either from Monitis dashboard or from specific API calls by providing your username and password.

  1. Log in to your Monitis account, go to Account → API key and find there both apikey and secretkey
  2. Make API call. get the apikey and secretkey by providing your username and password

Getting apikey and secretkey

Request:
http://api.monitis.com/api?action=apikey&userName=someAccount%40gmail.com&password=MonitisPassencrypted&output=xml
Response:
<result>
	<apikey>yourapikey</apikey>
	<secretkey>yoursecretkey</secretkey>
</result>

or

Request:
http://api.monitis.com/api?action=apikey&userName=someAccount@gmail.com&password=MonitisPassencrypted&output=json
Response:
{"apikey":"yourapikey","secretkey":"yoursecretkey"}

Where you should replace someaccount@gmail.com with your real username and MonitisPassencrypted with your real password encrypted by md5.

Now that you've got apikey and secretkey you need to know how to authenticate requests. There are 2 ways to do it

  1. Calculate a checksum for each request
  2. Obtain an authentication token and use it in all requests. The token is valid within 24 hours after generation. After then it should be regenerated.

Checksum

Checksum is a string constructed as follows:

  • sort all request parameters alphabetically by param name
  • join param-value pairs in a string: param1value1param2value2...
  • get Base64-encoded RFC 2104-compliant HMAC signature of the constructed string using your secretkey

Here is a Java example of calculating checksum

Example of getting Base64-encoded RFC 2104-compliant HMAC signature

Checksum calculation tool

Authentication Token

Authentication token can be obtained by making a special API request.

Request:
http://api.monitis.com/api?action=authToken&apikey=yourapikey&secretkey=yoursecretkey&output=xml
Response:
<authToken>authtokenstring</authToken>

or

Request:
http://api.monitis.com/api?action=authToken&apikey=yourapikey&secretkey=yoursecretkey&output=json
Response:
{"authToken":"authtokenstring"}

Where you should replace yourapikey and yoursecretkey with your real apikey and secretkey

API URL

For all actions covered under Api actions link API base url is http://api.monitis.com/api.
And for all actions covered under Custom API actions link API base url is http://api.monitis.com/customMonitorApi.

Request Structure

The list of required parameters for a request is a little bit different for checksum and authentication token validations.

Parameters for a request with checksum validation:

Name Value
apikey See getting apikey and secretkey
validation HMACSHA1
checksum See checksum calculation
timestamp Current datetime in GMT with yyyy-MM-dd HH:mm:ss format
output Valid values are xml or json
version 3
clientApikey Client's API key. This is a required parameter in all requests where reseller performs an action which effects client's account, e.g. add, edit or delete a monitor, contact, page or module.

Parameters for a request with authentication token validation:

Name Value
apikey See getting apikey and secretkey
validation token
authToken See getting authentication token
output Valid values are xml or json
version 3
clientApikey Client's API key. This is a required parameter in all requests where reseller performs an action which effects client's account, e.g. add, edit or delete a monitor, contact, page or module.

Response format

It is possible to specify response format by sending parameter named output. Available options are: XML and JSON. By default JSON is used.

Parameters Encoding

All parameters must be encoded. Valid encoding is URL encoding with charset UTF8. E.g. in Java language a method used for url encoding is java.net.URLEncoder.encode(String stringToEncode, String charset). See the doc.
In case the parameter has a certain format specified in the doc and has data delimiters such as ; or : then these kind of parameters should be double encoded to avoid mistakes where data unit contains symbols equivalent to delimiter. Here is how double encoding is done.
E.g. the parameter results in action addResult has the following format paramName1:paramValue1[;paramName2:paramValue2...]. Suppose you have function encode(stringToEncode). Double encoding will be done as below:
encode(encode( paramName1)+":"+encode(paramValue1)+";"+encode( paramName2)+":"+encode(paramValue2))
Each part of data (string between data separators - ; and : ) is encoded separately then the whole string is encoded.

Version 3 vs version 2

The current page describes api version 3. We don't keep a separate page for version 2 as there are few differences between api versions 2 and 3.
The 1st difference is that version 3 is more secure. It requires authentication by checksum or token both for GET and POST requests. In version 2 authentication of GET requests is very weak, the only required parameter is apikey.
The 2nd difference is that the mechanizm of Public Keys is available starting from version 3 and you should be aware that all coming new features won't be available in version 2 so we suggest you to switch to version 3 in case you are still using version 2.