API monitoringu

Aktivace API

Přístup do API lze aktivovat ve WEDOS administraci, kam se dostanete přes client.wedos.com v detailu konkrétní domény, u které máte tuto doplňkovou službu aktivovanou.

V administraci zvolte sekci Nastavení -> Nastavení API. Aktivací se vygeneruje API klíč (podobný heslu), který následně použijete pro autentizaci v API komunikaci.

Základní informace

Komunikace s API probíhá přes HTTPS metodou GET. Některé metody přijímají parametry v URL (GET parametry). Všechny metody vrací odpověď jako JSON objekt a všechna data jsou v kódování UTF-8.

Každá odpověď nese položku requestId, která jednoznačně identifikuje požadavek. Podle tohoto identifikátoru dohledáme konkrétní komunikaci v našem logu, pokud nastane problém nebo dotaz.

API se nachází na adrese https://api.wedos.online/mon/ následované názvem konkrétní metody. Autentizace používá dvě HTTP hlavičky posílané s každým požadavkem:

Hlavička	Hodnota
X-Auth-Id	ID vašeho API klíče
X-Auth-Key	váš API klíč

API má následující limity:

• max. 1000 požadavků za hodinu z jedné IP adresy
• max. 1000 požadavků za hodinu od jednoho uživatele

Ahoj světe

Toto je základní volání metody zvané ping, která jednoduše ověří, že spojení a autentizace fungují.

Požadavek

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

Odpověď

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

Při chybě vrátí HTTP server stavový kód jiný než 200 a tělo odpovědi upřesní chybu: kód chyby a její popis. Příklad:

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

Seznamy, filtrování, stránkování

Některé API metody vrací seznam položek (například kontroly). Tyto metody mají společné funkce, vstupní parametry i výstupní data. Výsledek vždy obsahuje následující položky:

Položka	Význam
results	pole objektů s jednotlivými položkami seznamu
page	číslo stránky (viz stránkování níže)
count	počet vrácených položek
filteredCount	počet všech položek odpovídajících aktuálnímu filtru
totalCount	počet všech položek

Příklad odpovědi (jednotlivé položky jsou zde vynechány):

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

Tato odpověď znamená, že pro aktuálního uživatele existuje celkem 624 položek (například kontrol), z toho 18 odpovídá aktivnímu filtru (filtrům) a vráceno bylo prvních 10 položek (první stránka, stránkování po 10 položkách).

V požadavku na seznam lze předat jeden nebo více filtrů jako GET parametry; vráceny jsou jen odpovídající položky. Položky seznamu lze stránkovat, tedy vracet jen v určitých rozsazích. API umožňuje maximálně 1000 položek na jedno volání a výchozí stránkování je 100 položek.

Následující GET parametry řídí stránkování a počet vracených položek:

Parametr	Význam
page	číslo stránky (výchozí 1)
count	počet vracených položek, tj. velikost stránky (výchozí 100)

Příklad výpisu 10 položek na druhé stránce (položky 11 až 20):

Seznam kontrol

Metoda zvaná checks načte seznam monitorovaných služeb ve vašem účtu.

Příklad odpovědi

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

Seznam lze filtrovat podle status a/nebo type, například:

Význam položek v odpovědi:

Pole	Význam
ID	ID kontroly
name	název kontroly
type	typ kontroly (ping, http, dns, smtp, ...)
period	interval testování (sekundy)
fullTarget	název hostitele/domény cíle (doménový název, server)
status	aktuální stav kontroly (ok, slow, response_timeout, down, response_error, disabled, ...)
statusStamp	poslední změna stavu (UNIX timestamp)
statusDate	poslední změna stavu (formát SQL, UTC)
createdStamp	datum a čas vytvoření kontroly (UNIX timestamp)
createdDate	datum a čas vytvoření kontroly (formát SQL, UTC)
uptime_1d	uptime za posledních 24 hodin (procenta)
errorSeconds_1d	sekundy v chybovém stavu za posledních 24 hodin
avgTime_1d	průměrný čas odezvy za posledních 24 hodin (sekundy)
uptime_7d	uptime za posledních 7 dní (procenta)
errorSeconds_7d	sekundy v chybovém stavu za posledních 7 dní
avgTime_7d	průměrný čas odezvy za posledních 7 dní (sekundy)
uptime_30d	uptime za posledních 30 dní (procenta)
errorSeconds_30d	sekundy v chybovém stavu za posledních 30 dní
avgTime_30d	průměrný čas odezvy za posledních 30 dní (sekundy)
warningsCount	počet aktivních varování

Stav může být:

Stav	Význam
unknown	test zatím neproběhl
ok	vše je v pořádku
slow	odpověď byla úspěšná, ale pomalá
response_timeout	spojení bylo navázáno, ale vypršel čas při čekání na odpověď
down	spojení selhalo
response_error	chybná odpověď
maintenance	kontrola je v plánované údržbě
paused	kontrola je pozastavena, testy se neprovádí
disabled	kontrola byla zakázána administrátorem
denied	monitoring odmítl provést test, obvykle protože se cíl překládá na IP adresu v privátním rozsahu
unverified	neověřili jste vlastnictví webu, který chcete monitorovat (platí pro HTTP kontroly)
invalidStatus	jiný chybný stav monitorované služby

Detail kontroly

Metoda check zobrazí více detailů o jedné konkrétní kontrole (monitorované službě). Do URL přidáte ID kontroly, například:

Příklad odpovědi

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

Doplňující informace o kontrole:

Pole	Význam
lastTestStamp	naposledy provedený test (UNIX timestamp)
lastTestDate	naposledy provedený test (formát SQL, UTC)
requestTime	čas odezvy z posledního testu (ms), pokud je k dispozici
info	doplňující informace (chybová zpráva, detaily odpovědi)
testsCount	počet testů od úplného počátku
errorsCount	počet chybových výsledků od úplného počátku
pendingErrorsCount	počet aktuálních chyb
lastErrorBeginStamp	začátek aktuálního chybového stavu (UNIX timestamp)
ip	IP adresa cíle (pokud je k dispozici)
ptr	reverzní záznam (PTR) cíle (pokud je k dispozici)
nextStamp	přibližné datum a čas dalšího testu (UNIX timestamp)
warnings	pole dodatečných varování (expirace certifikátu, IP na blocklistech, méně závažné chyby odpovědi atd.)