WEDOS Early Warning and Monitoring (EWM) nabízí API rozhraní, tedy programové rozhraní, pomocí kterého si uživatelé mohou zjišťovat informace o svých monitorovaných doménách, kontrolách služeb a jejich aktuálním stavu. Mohou si tak naprogramovat propojení monitoringu se svou aplikací či automatizovaně sledovat nové události u monitorovaných domén a služeb.
Toto API je k dispozici pouze ve variantě služby HighAvailability.
Aktivace API
Přístup do API je možné aktivovat v administraci EWM, kam se dostanete skrz stránky client.wedos.com v detailu konkrétní domény, u které máte aktivní tuto příplatkovou službu. V administraci EWM zvolte Nastavení -> sekce 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 rozhraním probíhá pomocí HTTPS, používá se metoda GET. Některé metody přijímají parametry v URL adrese (GET parametry).
Všechny metody vrací odpověď ve formě JSON objektu. Všechna data v odpovědi jsou v kódování UTF-8.
V každé odpovědi se nachází položka requestId, která daný požadavek jednoznačně identifikuje. Podle tohoto identifikátoru jsme schopni u nás v logu dohledat konkrétní komunikaci v případě, že nastane nějaký problém či dotaz.
API rozhraní se nachází na adrese https://api.wedos.online/mon/ + název konkrétní metody.
Autentizace uživatele se provádí pomocí speciálních HTTP hlaviček – v každém požadavku se uvede ID API klíče (X-Auth-Id) a API klíč (X-Auth-Key).
API rozhraní má následující omezení:
- 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 volání metody zvané ping, díky které si snadno ověříte, že API komunikace a autentizace fungují.
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
Odpověď by měla vypadat nějak takto:
{
"stamp": 1613393366,
"time": "2021-02-15 13:49:26",
"userId": 1000,
"requestId": "3bb52d4d22.1613393366.2811.82063"
}
V případě chyby vrátí server HTTP kód odpovědi jiný než 200 a v těle odpovědi je upřesnění chyby – je uveden 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 nějakých položek (např. seznam domén). Tyto metody mají společné funkce a společné vstupní parametry a výstupní data.
Součástí výsledku volání metod pro čtení seznamů jsou vždy následující položky:
- results – pole objektů s jednotlivými položkami seznamu
- page – číslo stránky (viz. dále stránkování)
- count – počet vrácených položek
- filteredCount – počet všech položek, které odpovídají aktuálnímu filtru (viz. dále filtrování)
- 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 konkrétní odpověď znamená, že v databázi pro aktuálního uživatele existuje celkem 624 položek (např. domén), z toho 18 odpovídá nastaveným filtrům a vráceno bylo prvních 10 (první stránka, stránkování po 10 položkách).
V požadavku na seznam lze uvést jeden nebo více filtrů. Ty se uvádí jako GET parametry. Podle toho se vyberou položky, které jsou vráceny.
Položky seznamů lze stránkovat, tedy vracet jen po určitých počtech. API umožňuje vrácení nejvýše 1000 položek při jednom volání. Výchozí stránkování je 100 položek.
Pro stránkování a/nebo omezení počtu vracených položek lze použít tyto vstupní GET parametry:
- 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 (tedy položky 11 až 20):
https://api.wedos.online/mon/domains?page=2&count=10
Seznam domén
Metoda zvaná domains vám umožňuje získat seznam vašich domén, které jsou monitorovány pomocí EWM.
URL požadavku:
https://api.wedos.online/mon/domains
Příklad odpovědi:
{
"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"
}
Zde můžete vidět celkový stav všech vašich monitorovaných domén a seznam kontrol, který jsou u každé domény prováděny.
Pokud chcete znát podrobnosti, můžete získat detail konkrétní domény pomocí metody domain anebo detail konkrétní kontroly pomocí metody check (použijte hodnotu checkId jako identifikátor konkrétní kontroly).
Detail domény
Pro získání detailních informací o jedné konkrétní doméně a jejích kontrolách (monitorovaných službách) použijte metodu domain.
https://api.wedos.online/mon/domain/24
Příklad odpovědi (výstup byl zkrácen):
{
"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"
}
Význam jednotlivých položek v odpovědi:
- ID – ID domény
- name – název domény
- checkId – ID kontroly
- type – typ kontroly (ping, http, dns, smtp, …)
- period – interval testování (sekundy)
- fullTarget – název serveru či doménový název cíle
- 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 – vytvoření kontroly (UNIX timestamp)
- createdDate – vytvoření kontroly (formát SQL, UTC)
- uptime_1d – uptime za posledních 24 hodin (procenta)
- errorSeconds_1d – délka trvání chybových stavů za posledních 24 hodin (sekundy)
- avgTime_1d – průměrná rychlost odezvy za posledních 24 hodin (sekundy)
- uptime_7d – uptime za posledních 7 dní (procenta)
- errorSeconds_7d – délka trvání chybových stavů za posledních 7 dní (sekundy)
- avgTime_7d – průměrná rychlost odezvy za posledních 7 dní (sekundy)
- uptime_30d – uptime za posledních 30 dní (procenta)
- errorSeconds_30d – délka trvání chybových stavů za posledních 7 dní (sekundy)
- avgTime_30d – průměrná rychlost odezvy za posledních 30 dní (sekundy)
- warningsCount – počet aktivních varování
Stavy mohou být:
- unknown – test zatím neproběhl
- ok – všechno je v pořádku
- slow – odpověď byla v pořádku, ale pomalá
- response_timeout – navázání spojení bylo v pořádku, ale během čekání na odpověď vypršel čas
- down – spojení se nezdařilo
- response_error – chybná odpověď
- maintenance – u kontroly právě probíhá plánovaná odstávka
- paused – kontrola je pozastavena, testy se neprovádí
- disabled – kontrola byla zakázána administrátorem
- denied – monitoring odmítl provést test – obvykle to znamená, že se pokoušíte spojovat na IP adresu spadající do privátního rozsahu
- invalidStatus – jiný chybový stav monitorované služby
Detail kontroly
Pokud chcete vidět ještě detailnější informace o konkrétní kontrole konkrétní domény, je k dispozici metoda check. Do URL přidejte ID kontroly, např.:
https://api.wedos.online/mon/check/5178
Příklad odpovědi:
{
"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"
}
Význam dodatečných položek v odpovědi:
- lastTestStamp – poslední test (UNIX timestamp)
- lastTestDate – poslední test (formát SQL, UTC)
- requestTime – čas odezvy v posledním testu (ms), pokud je k dispozici
- info – dodatečné informace (chybová hláška, detail odpovědi)
- testsCount – celkový počet provedených testů od počátku
- errorsCount – celkový počet chyb od počátku
- pendingErrorsCount – počet chyb v rámci aktuálního chybového stavu
- lastErrorBeginStamp – počátek aktuálního chybového stavu (UNIX timestamp)
- ip – IP adresa cíle (pokud je k dispozici)
- ptr – reverzní záznam cíle (PTR) (pokud je k dispozici)
- nextStamp – přibližný čas následujícího testu (UNIX timestamp)
- warnings – seznam dodatečných varování (blížící se expirace certifikátu, IP adresa na blocklistech, méně závažné chyby v odpovědi aj.)