WEDOS EWM – dokumentacja API

Aktywacja API

Dostęp do API można aktywować w administracji EWM, do której wejdziesz przez client.wedos.com w szczegółach konkretnej domeny, dla której masz aktywną tę płatną usługę. W administracji EWM wybierz Ustawienia -> sekcja Ustawienia API. Aktywacja generuje klucz API (podobny do hasła), którego następnie użyjesz do uwierzytelnienia w komunikacji API.

Podstawowe informacje

Komunikacja z API odbywa się przez HTTPS, metodą GET. Niektóre metody przyjmują parametry w adresie URL (parametry GET).

Wszystkie metody zwracają odpowiedź w postaci obiektu JSON. Wszystkie dane w odpowiedzi są w kodowaniu UTF-8.

W każdej odpowiedzi znajduje się pozycja requestId, która jednoznacznie identyfikuje żądanie. Na podstawie tego identyfikatora jesteśmy w stanie odnaleźć konkretną komunikację w naszym logu, gdy pojawi się problem lub pytanie.

API znajduje się pod adresem https://api.wedos.online/mon/ + nazwa konkretnej metody.

Uwierzytelnianie użytkownika odbywa się za pomocą specjalnych nagłówków HTTP – w każdym żądaniu podaje się ID klucza API (X-Auth-Id) oraz klucz API (X-Auth-Key).

API ma następujące ograniczenia:

• maks. 1000 żądań na godzinę z jednego adresu IP
• maks. 1000 żądań na godzinę od jednego użytkownika

Witaj świecie!

To wywołanie metody o nazwie ping, dzięki której łatwo sprawdzisz, że komunikacja API i uwierzytelnianie działają.

Żądanie

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

Odpowiedź powinna wyglądać mniej więcej tak

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

W przypadku błędu serwer zwraca kod odpowiedzi HTTP inny niż 200, a w treści odpowiedzi jest doprecyzowanie błędu: podany jest kod błędu i jego opis. Przykład:

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

Listy, filtrowanie, stronicowanie

Niektóre metody API zwracają listę pozycji (np. listę domen). Metody te mają wspólne funkcje oraz wspólne parametry wejściowe i dane wyjściowe.

Częścią wyniku metod odczytu list są zawsze następujące pozycje:

Przykład odpowiedzi (poszczególne pozycje nie są tu podane):

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

Ta konkretna odpowiedź oznacza, że w bazie dla bieżącego użytkownika istnieje łącznie 624 pozycji (np. domen), z czego 18 pasuje do ustawionych filtrów, a zwrócono pierwszych 10 (pierwsza strona, stronicowanie po 10 pozycji).

W żądaniu listy można podać jeden lub więcej filtrów. Podaje się je jako parametry GET. Na tej podstawie wybierane są zwracane pozycje.

Pozycje list można stronicować, czyli zwracać tylko w określonych ilościach. API pozwala zwrócić maksymalnie 1000 pozycji na jedno wywołanie. Domyślne stronicowanie to 100 pozycji.

Do stronicowania i/lub ograniczenia liczby zwracanych pozycji można użyć tych wejściowych parametrów GET:

Przykład wypisania 10 pozycji na drugiej stronie (pozycje 11 do 20):

Lista domen

Metoda o nazwie domains umożliwia pobranie listy Twoich domen monitorowanych przez EWM.

URL żądania:

Przykład odpowiedzi

{
    "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"
}

Tutaj widzisz ogólny status wszystkich monitorowanych domen oraz listę kontroli wykonywanych dla każdej domeny.

Jeśli chcesz poznać szczegóły, możesz pobrać szczegóły konkretnej domeny metodą domain albo szczegóły konkretnej kontroli metodą check (użyj wartości checkId jako identyfikatora konkretnej kontroli).

Szczegóły domeny

Aby uzyskać szczegółowe informacje o jednej konkretnej domenie i jej kontrolach (monitorowanych usługach), użyj metody domain.

Przykład odpowiedzi (wynik został skrócony)

{
    "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"
}

Znaczenie poszczególnych pozycji w odpowiedzi:

Statusy mogą być:

Szczegóły kontroli

Jeśli chcesz zobaczyć jeszcze bardziej szczegółowe informacje o konkretnej kontroli konkretnej domeny, dostępna jest metoda check. Do URL dodaj ID kontroli, np.:

Przykład odpowiedzi

{
    "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"
}

Znaczenie dodatkowych pozycji w odpowiedzi: