API monitoringu

Aktywacja API

Dostęp do API aktywuje się w panelu WEDOS, do którego wejdziesz przez client.wedos.com w szczegółach konkretnej domeny, dla której masz aktywowaną tę usługę dodatkową.

W panelu wybierz sekcję Ustawienia -> Ustawienia API. Aktywacja generuje klucz API (podobny do hasła), którego następnie używasz do uwierzytelniania w komunikacji z 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ź jako obiekt JSON, a wszystkie dane są w kodowaniu UTF-8.

Każda odpowiedź zawiera pozycję requestId, która jednoznacznie identyfikuje żądanie. Na podstawie tego identyfikatora w razie problemu lub pytania potrafimy odnaleźć konkretną komunikację w naszym logu.

API znajduje się pod adresem https://api.wedos.online/mon/, po którym następuje nazwa konkretnej metody. Uwierzytelnianie odbywa się za pomocą dwóch nagłówków HTTP wysyłanych przy każdym żądaniu:

Nagłówek	Wartość
X-Auth-Id	ID Twojego klucza API
X-Auth-Key	Twój klucz API

API ma następujące limity:

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

Hello World

To podstawowe wywołanie metody ping, która po prostu sprawdza, że połączenie i uwierzytelnianie działają.

Żądanie

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

Odpowiedź

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

Przy błędzie serwer HTTP zwraca kod statusu inny niż 200, a treść odpowiedzi precyzuje błąd: podaje 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 (na przykład kontroli). Metody te mają wspólne funkcje, parametry wejściowe i dane wyjściowe. Wynik zawsze zawiera następujące pozycje:

Pozycja	Znaczenie
results	tablica obiektów z poszczególnymi pozycjami listy
page	numer strony (patrz stronicowanie poniżej)
count	liczba zwróconych pozycji
filteredCount	liczba wszystkich pozycji pasujących do aktualnego filtra
totalCount	liczba wszystkich pozycji

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

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

Ta odpowiedź oznacza, że dla aktualnego użytkownika jest łącznie 624 pozycji (na przykład kontroli), z których 18 pasuje do aktywnego filtra, a zwrócono pierwsze 10 pozycji (pierwsza strona, stronicowanie po 10 pozycjach).

W żądaniu listy można jako parametry GET przekazać jeden lub więcej filtrów; zwracane są tylko pasujące pozycje. Pozycje listy można stronicować, czyli zwracać tylko w określonych zakresach. API pozwala na maksymalnie 1000 pozycji na jedno wywołanie, domyślne stronicowanie to 100 pozycji.

Do stronicowania i ograniczenia liczby zwracanych pozycji służą następujące parametry GET:

Parametr	Znaczenie
page	numer strony (domyślnie 1)
count	liczba zwracanych pozycji, czyli rozmiar strony (domyślnie 100)

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

Lista kontroli

Metoda checks pobiera listę monitorowanych usług na Twoim koncie.

Przykład odpowiedzi

{
    "results": [
        {
            "ID": 5151,
            "name": "seznam.cz DNSSEC",
            "type": "dnssec",
            "period": 600,
            "fullTarget": "seznam.cz",
            "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
        },
        ...
    ],
    "page": 1,
    "count": 21,
    "filteredCount": 21,
    "totalCount": 21,
    "requestId": "3bb52d4d22.1613394688.5186.82182"
}

Listę możesz filtrować według status i/lub type, na przykład:

Znaczenie pozycji w odpowiedzi:

Pozycja	Znaczenie
ID	ID kontroli
name	nazwa kontroli
type	typ kontroli (ping, http, dns, smtp, ...)
period	interwał testu (sekundy)
fullTarget	host/nazwa domeny celu (domena, serwer)
status	aktualny stan kontroli (ok, slow, response_timeout, down, response_error, disabled, ...)
statusStamp	ostatnia zmiana stanu (UNIX timestamp)
statusDate	ostatnia zmiana stanu (format SQL, UTC)
createdStamp	data i czas utworzenia kontroli (UNIX timestamp)
createdDate	data i czas utworzenia kontroli (format SQL, UTC)
uptime_1d	dostępność za ostatnie 24 godziny (procenty)
errorSeconds_1d	liczba sekund w stanie błędu za ostatnie 24 godziny
avgTime_1d	średni czas odpowiedzi za ostatnie 24 godziny (sekundy)
uptime_7d	dostępność za ostatnie 7 dni (procenty)
errorSeconds_7d	liczba sekund w stanie błędu za ostatnie 7 dni
avgTime_7d	średni czas odpowiedzi za ostatnie 7 dni (sekundy)
uptime_30d	dostępność za ostatnie 30 dni (procenty)
errorSeconds_30d	liczba sekund w stanie błędu za ostatnie 30 dni
avgTime_30d	średni czas odpowiedzi za ostatnie 30 dni (sekundy)
warningsCount	liczba aktywnych ostrzeżeń

Stan (status) może być:

Stan	Znaczenie
unknown	test jeszcze nie został wykonany
ok	wszystko jest w porządku
slow	odpowiedź była udana, ale wolna
response_timeout	połączenie się powiodło, ale upłynął limit czasu oczekiwania na odpowiedź
down	połączenie nie powiodło się
response_error	nieprawidłowa odpowiedź
maintenance	kontrola jest w zaplanowanej konserwacji
paused	kontrola jest wstrzymana, testy nie są wykonywane
disabled	kontrola została wyłączona przez administratora
denied	system monitorujący odmówił wykonania testu, zwykle oznacza to, że cel wskazuje na adres IP z zakresu prywatnego
unverified	nie zweryfikowałeś własności strony, którą chcesz monitorować (dotyczy kontroli HTTP)
invalidStatus	inny nieprawidłowy stan monitorowanej usługi

Szczegóły kontroli

Metoda check pokazuje szczegóły jednej konkretnej kontroli (monitorowanej usługi). Do adresu URL dodajesz ID kontroli, na przykład:

Przykład odpowiedzi

{
    "check": {
        "ID": 5151,
        "name": "seznam.cz DNSSEC",
        "type": "dnssec",
        "period": 600,
        "fullTarget": "seznam.cz",
        "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": "seznam.cz/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"
}

Dodatkowe informacje o kontroli:

Pozycja	Znaczenie
lastTestStamp	ostatnio wykonany test (UNIX timestamp)
lastTestDate	ostatnio wykonany test (format SQL, UTC)
requestTime	czas odpowiedzi z ostatniego testu (ms), jeśli dostępny
info	dodatkowe informacje (komunikat błędu, szczegóły odpowiedzi)
testsCount	liczba testów od samego początku
errorsCount	liczba błędnych wyników od samego początku
pendingErrorsCount	liczba aktualnych błędów
lastErrorBeginStamp	początek aktualnego stanu błędu (UNIX timestamp)
ip	adres IP celu (jeśli dostępny)
ptr	rekord odwrotny (PTR) celu (jeśli dostępny)
nextStamp	przybliżona data i czas kolejnego testu (UNIX timestamp)
warnings	tablica dodatkowych ostrzeżeń (wygaśnięcie certyfikatu, IP na listach blokujących, mniej poważne błędy odpowiedzi itp.)