WEDOS EWM – API documentation

WEDOS EWM - API documentation

WEDOS Early Warning and Monitoring (EWM) offers API, an application program interface to help users to find out information about their domains, service checks and their current status. They can connect our monitoring system with their application or automatically monitor new events for controlled services.

This API is available only in HighAvailability subscription.

API activation

You can activate API access after logging in to the EWM control panel, which can be accessed through client.wedos.com in the detail of particular domain. In EWM control panel, go to Settings -> API settings section. Activation will generate an API key (similar to a password), which you will then use for authentication in API requests.

Basic information

Communication with the API interface takes place using HTTPS, the GET method is used. Some methods accept parameters in the URL (GET parameters).

All methods return a response in the form of a JSON object. All data in the response is in UTF-8 encoding.

Each response has a requestId entry that uniquely identifies the request. According to this identifier, we are able to find specific communication in our log in the event that a problem or question arises.

The API is located at https://api.wedos.online/mon/ + the name of the specific method.

User authentication is performed using special HTTP headers – each request includes API key ID (X-Auth-Id) and API key (X-Auth-Key).

The API has the following limitations:

max. 1000 requests per hour from one IP address
max. 1000 requests per hour from one user

Hello world!

This is a basic call to a method called ping, which simply checks that the connection and authentication works.

GET /mon/ping HTTP/1.1
Host: api.wedos.online
Accept: application/json
X-Auth-Id: me@example.com
X-Auth-Key: MY_API_KEY

And the response could look like this:

{
    "stamp": 1613393366,
    "time": "2021-02-15 13:49:26",
    "userId": 1000,
    "requestId": "3bb52d4d22.1613393366.2811.82063"
}

In case of an error, the HTTP server returns a response code other than 200 and there is an specification of the error in the body of the response – the error code and its description are given. Example:

{
    "error": {
        "code": "C507",
        "error": "Authentication failed"
    },
    "requestId": "1495544185.1615.8422"
}

Lists, filtering, paging

Some API methods return a list of some items (for example domains). These methods have common functions and common input parameters and output data.

The result always includes the following items:

results – array of objects with individual list items
page – page number (see paging below)
count – number of returned items
filteredCount – number of all items that correspond to the current filter (see filtering below)
totalCount – number of all items

Example response (specific items are not listed here):

{
    "results": [
        ...
    ],
    "page": 1,
    "count": 10,
    "filteredCount": 18,
    "totalCount": 624,
    "requestId": "..."
}

This particular response means that there are a total of 624 items in the database for the current user (eg. domains), of which 18 correspond to active filter(s) and the first 10 items were returned (first page, paging after 10 items).

One or more filters can be specified in the list request. These are referred to as GET parameters. The items that are selected are returned accordingly.

List items can be paged, ie returned only after certain numbers. The API allows a maximum of 1000 items per call. The default paging is 100 items.

The following input GET parameters can be used for paging and / or limiting the number of returned items:

page – page number (default 1)
count – number of returned items, ie page size (default 100)

Example of a listing of 10 items on the second page (ie items 11 to 20):

https://api.wedos.online/mon/domains?page=2&count=10

Domains list

A method called domains allow you to fetch the list of your domain names that are being monitored.

Request URL:

https://api.wedos.online/mon/domains

Response example:

{
    "results": [
        {
            "ID": 24,
            "name": "example.com",
            "status": "warning",
            "checks": {
                "domain": {
                    "checkId": null
                },
                "http": {
                    "checkId": 5056
                },
                "dnsauth": {
                    "checkId": 5052
                },
                "dnssec": {
                    "checkId": 5178
                },
                "mx": {
                    "checkId": 5093
                },
                "smtp": {
                    "checkId": 5066
                },
                "pop3": {
                    "checkId": 5095
                },
                "imap": {
                    "checkId": 5098
                },
                "ftp": {
                    "checkId": 5183
                },
                "ssh": {
                    "checkId": 5184
                },
                "spf": {
                    "checkId": 5110
                }
            }
        }
    ],
    "page": 1,
    "count": 1,
    "filteredCount": 1,
    "totalCount": 1,
    "requestId": "3bb52d4d22.1615325171.8202.150654"
}

You can see overall status of all your domain names and the list of checks that are performed on each domain.

If you want to see more details, you can get the detail of one domain using domain method or detail of particular check using check method (you use checkId as particular check identifier).

Domain detail

To see more details about one domain and all its checks (monitored services), use domain method.

https://api.wedos.online/mon/domain/24

Response example (the output was significantly shortened):

{
    "domain": {
        "ID": 24,
        "name": "example.com",
        "status": "warning",
        "checks": {
            "domain": {
                "checkId": null
            },
            "http": {
                "checkId": 5056,
                "status": "ok",
                "name": "example.com HTTP",
                "type": "http",
                "period": 60,
                "fullTarget": "https://example.com/",
                "domainId": 24,
                "statusStamp": 1613140656,
                "statusDate": "2021-02-12 14:37:36",
                "createdStamp": 1604348089,
                "createdDate": "2020-11-02 20:14:49",
                "uptime_1d": 100,
                "errorSeconds_1d": 0,
                "avgTime_1d": 111,
                "uptime_7d": 100,
                "errorSeconds_7d": 0,
                "avgTime_7d": 109,
                "uptime_30d": 99.994,
                "errorSeconds_30d": 57,
                "avgTime_30d": 114,
                "warningsCount": 0
            },
            "dnsauth": {
                ...
            },
            "dnssec": {
                ...
            },
            "mx": {
                ...
            },
            "smtp": {
                ...
            },
            "pop3": {
                ...
            },
            "imap": {
                ...
            },
            "ftp": {
                ...
            },
            "ssh": {
                ...
            },
            "spf": {
                ...
            }
        }
    },
    "requestId": "3bb52d4d22.1615325829.4246.150888"
}

The meaning of the items in the response:

ID – domain ID
name – domain name
checkId – check ID
type – check type (ping, http, dns, smtp, …)
period – test interval (seconds)
fullTarget – host/domain name of the target (domain name, server)
status – current check status (ok, slow, response_timeout, down, response_error, disabled, …)
statusStamp – last status change (UNIX timestamp)
statusDate – last status change (SQL format, UTC)
createdStamp – check creation date and time (UNIX timestamp)
createdDate – check creation date and time (SQL format, UTC)
uptime_1d – uptime in the last 24 hours (percent)
errorSeconds_1d – number of second in error state in the last 24 hours
avgTime_1d – average response time in the last 24 hours (seconds)
uptime_7d – uptime inthe last 7 days (percent)
errorSeconds_7d – number of second in error state in the last 7 days
avgTime_7d – average response time in the last 7 days (seconds)
uptime_30d – uptime inthe last 30 days (percent)
errorSeconds_30d – number of second in error state in the last 30 days
avgTime_30d – average response time in the last 30 days (seconds)
warningsCount – number of active warnings

The status can be:

unknown – test not performed yet
ok – everything is okay
slow – response was successful, but slow
response_timeout – connection was successful, but got timeout when waiting for a response
down – connection failed
response_error – invalid response
maintenance – check is in planned maintenance
paused – check is paused, no tests are performed
disabled – check was disabled by an administrator
denied – the monitoring system refused to perform the test, usually it means that you are trying to connect to an IP address that belongs to a private range
invalidStatus – other invalid status of monitored service

Check detail

If you want to get the most detailed information about one particular check of one particular domain name, there is a check method for that. Simply add the ID of the check to the URL adress, example:

https://api.wedos.online/mon/check/5178

Response example:

{
    "check": {
        "ID": 5178,
        "name": "example.com DNSSEC",
        "type": "dnssec",
        "period": 600,
        "fullTarget": "example.com",
        "status": "ok",
        "statusStamp": 1612886736,
        "statusDate": "2021-02-09 16:05:36",
        "createdStamp": 1612886708,
        "createdDate": "2021-02-09 16:05:08",
        "uptime_1d": 100,
        "errorSeconds_1d": 0,
        "avgTime_1d": 0,
        "uptime_7d": 100,
        "errorSeconds_7d": 0,
        "avgTime_7d": 0,
        "uptime_30d": 100,
        "errorSeconds_30d": 0,
        "avgTime_30d": 0,
        "warningsCount": 0,
        "lastTestStamp": 1613396132,
        "lastTestDate": "2021-02-15 13:35:32",
        "requestTime": null,
        "info": "example.com/SOA secured by DNSSEC\nSignature expiration: 2021-02-28 16:01:01 UTC",
        "testsCount": 363,
        "errorsCount": 0,
        "pendingErrorsCount": 0,
        "lastErrorBeginStamp": null,
        "ip": null,
        "ptr": null,
        "nextStamp": 1613396731,
        "warnings": []
    },
    "requestId": "3bb52d4d22.1613396687.4247.82403"
}

The meaning of additional items in the response:

lastTestStamp – test last performed (UNIX timestamp)
lastTestDate – test last performed (SQL format, UTC)
requestTime – response time from the last test (ms), if available
info – additional information (error message, response details)
testsCount – number of tests from the very beginning
errorsCount – number of error results from the very beginning
pendingErrorsCount – number of current errors
lastErrorBeginStamp – date and time of the beginning of the current error status (UNIX timestamp)
ip – IP address of the target (if available)
ptr – reverse record (PTR) of the target (if available)
nextStamp – approximate date and time of the next test (UNIX timestamp)
warnings – array of additional warnings (certificate expiration, IP on blocklists, less severe response errors etc.)