WEDOS EWM – API dokumentace

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í.

Požadavek

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:

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:

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

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:

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.

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:

Stavy mohou být:

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ř.:

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: