API monitoringu

Aktivace API

Přístup k API se aktivuje ve správě WEDOS, do které se dostanete přes client.wedos.com v detailu konkrétní domény, pro kterou máte tuto doplňkovou službu aktivovanou.

Ve správě zvolte sekci Nastavení -> Nastavení API. Aktivací se vygeneruje API klíč (podobný heslu), který pak použijete k autentizaci při komunikaci s API.

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 vracejí odpověď jako JSON objekt a všechna data jsou v kódování UTF-8.

Každá odpověď obsahuje položku requestId, která jednoznačně identifikuje požadavek. Podle tohoto identifikátoru dokážeme v případě problému nebo dotazu dohledat konkrétní komunikaci v našem logu.

API se nachází na adrese https://api.wedos.online/mon/ následované názvem konkrétní metody. Autentizace probíhá pomocí dvou HTTP hlaviček posílaných u každého požadavku:

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

Hello World

Toto je základní volání metody 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 jiný stavový kód než 200 a tělo odpovědi chybu specifikuje: uvede chybový kód a jeho popis. Příklad:

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

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

Některé metody API vracejí seznam položek (například kontrol). Tyto metody mají společné funkce, vstupní parametry i výstupní data. Výsledek vždy obsahuje tyto 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 (konkrétní položky zde nejsou uvedeny):

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

Tato odpověď znamená, že pro aktuálního uživatele je celkem 624 položek (například kontrol), z nichž 18 odpovídá aktivnímu filtru, 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 jako GET parametry předat jeden či více filtrů; vrátí se pouze 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í, výchozí stránkování je 100 položek.

Pro stránkování a omezení počtu vrácených položek slouží tyto GET parametry:

Parametr	Význam
page	číslo stránky (výchozí 1)
count	počet vrácený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 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 můžete filtrovat podle status a/nebo type, například:

Význam položek v odpovědi:

Položka	Význam
ID	ID kontroly
name	název kontroly
type	typ kontroly (ping, http, dns, smtp, ...)
period	interval testu (sekundy)
fullTarget	host/doménové jméno cíle (doména, 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 (SQL formát, UTC)
createdStamp	datum a čas vytvoření kontroly (UNIX timestamp)
createdDate	datum a čas vytvoření kontroly (SQL formát, UTC)
uptime_1d	dostupnost za posledních 24 hodin (procenta)
errorSeconds_1d	počet sekund v chybovém stavu za posledních 24 hodin
avgTime_1d	průměrná odezva za posledních 24 hodin (sekundy)
uptime_7d	dostupnost za posledních 7 dní (procenta)
errorSeconds_7d	počet sekund v chybovém stavu za posledních 7 dní
avgTime_7d	průměrná odezva za posledních 7 dní (sekundy)
uptime_30d	dostupnost za posledních 30 dní (procenta)
errorSeconds_30d	počet sekund v chybovém stavu za posledních 30 dní
avgTime_30d	průměrná odezva za posledních 30 dní (sekundy)
warningsCount	počet aktivních varování

Stav (status) může být:

Stav	Význam
unknown	test ještě nebyl proveden
ok	vše je v pořádku
slow	odpověď byla úspěšná, ale pomalá
response_timeout	spojení proběhlo, ale vypršel čas při čekání na odpověď
down	spojení selhalo
response_error	neplatná odpověď
maintenance	kontrola je v plánované údržbě
paused	kontrola je pozastavena, testy se neprovádějí
disabled	kontrolu zakázal administrátor
denied	monitorovací systém odmítl provést test, obvykle to znamená, že cíl míří na IP adresu z privátního rozsahu
unverified	neověřili jste vlastnictví webu, který chcete monitorovat (platí pro HTTP kontroly)
invalidStatus	jiný neplatný stav monitorované služby

Detail kontroly

Metoda check zobrazí podrobnosti 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:

Položka	Význam
lastTestStamp	poslední provedený test (UNIX timestamp)
lastTestDate	poslední provedený test (SQL formát, UTC)
requestTime	odezva z posledního testu (ms), pokud je dostupná
info	doplňující informace (chybová zpráva, detaily odpovědi)
testsCount	počet testů od úplného začátku
errorsCount	počet chybových výsledků od úplného začá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 dostupná)
ptr	reverzní záznam (PTR) cíle (pokud je dostupný)
nextStamp	přibližné datum a čas dalšího testu (UNIX timestamp)
warnings	pole doplňkových varování (expirace certifikátu, IP na blocklistech, méně závažné chyby odpovědi atd.)