WAPI – příručka

V tomto článku se dozvíte:

• Jak WAPI funguje
  • Podporované služby
  • Omezení požadavků
  • Synchronní a asynchronní požadavky
  • Návratové kódy
• Jak aktivovat WAPI v administraci WEDOS Global
• Jak WAPI integrovat do vašeho systému
• Základní požadavky pro otestování funkcí WAPI
• Řešení nejčastějších problémů
• Často kladené dotazy

---

WEDOS API (WAPI)

WEDOS API, zkráceně WAPI, slouží ke správě služeb WEDOS přímo z vašeho systému pomocí požadavků a odpovědí.

• Komunikace probíhá buď synchronní (odpověď se zpracuje obvykle během několika sekund od přijetí požadavku), nebo asynchronní (některé odpovědi mohou trvat déle; průběh sledujete pomocí notifikací).
• Data se předávají protokolem HTTPS metodou POST v parametru request; kódování dat je UTF-8.
• Podporované formáty jsou XML a JSON.

Podporované služby

WAPI aktuálně podporuje následující služby WEDOS Global:

• Členové WEDOS Global
• WEDOS Protection
• WEDOS DNS a NSSET

Dále máte přístup ke službám registrátora domén WEDOS:

• Domény
• Kontakty domén
• Zálohový účet

Omezení WAPI

Jako ochrana proti zneužití platí pro WAPI následující omezení:

• Jeden uživatelský účet může odeslat maximálně 1000 požadavků za hodinu. Platí to pro všechny typy požadavků. Po dosažení tohoto limitu WAPI další požadavky odmítá, dokud neuplyne časový limit.
• Jeden uživatelský účet může odeslat maximálně 100 požadavků na dostupnost domény za hodinu. Platí to pro požadavky domain-check, domain-create a domain-transfer-check.
• Opakované neplatné požadavky (selhání autorizace, přístup z nepovolené IP adresy, chybný vstup, chybějící nebo nesprávné parametry, neznámé příkazy, příkazy končící chybou nebo jakýkoli požadavek nad rámec dalších omezení) způsobí zablokování IP adresy na 1 minutu za každý neplatný požadavek nad 10. S každým dalším neplatným požadavkem systém dobu blokování prodlužuje.

Synchronní a asynchronní požadavky

Většina požadavků prováděných přes WAPI je synchronních – odešlete požadavek a výsledek obvykle dostanete během několika sekund.

Některé požadavky jsou asynchronní – jejich zpracování může trvat velmi dlouho (i hodiny nebo dny). V takovém případě WAPI nevrací konečný výsledek, ale pouze informaci o přijetí požadavku. Informace o průběhu a konečném výsledku vám pak systém posílá formou notifikací.

Návratové kódy

Návratové kódy udávají stav odpovědi WAPI. Některé kódy jsou specifické pro konkrétní požadavek a najdete je v příslušné dokumentaci WAPI; níže uvedený seznam platí pro všechny požadavky.

• 1000 = OK
• 2000 = Chyba při zpracování požadavku
• 2001 = Neplatný požadavek – chybí povinný parametr: user
• 2002 = Neplatný požadavek – chybí povinný parametr: auth
• 2003 = Neplatný požadavek – chybí povinný parametr: command
• 2004 = Neplatný požadavek – povolen je pouze jeden prvek data
• 2005 = Neplatný požadavek – parametr clTRID je příliš dlouhý
• 2006 = Překročen limit požadavků
• 2007 = Neplatný požadavek – překročena maximální velikost požadavku
• 2008 = Neplatný požadavek – požadavek je příliš složitý
• 2009 = Neplatný požadavek – požadavek je prázdný
• 2010 = Neznámý příkaz
• 2011 = Příkaz je zakázán
• 2050 = Selhání autentizace
• 2051 = Přístup z této IP adresy není povolen
• 2052 = IP adresa je dočasně zablokována kvůli příliš mnoha chybným požadavkům
• 2100 = Chybí povinný parametr
• 2101 = Neshoda parametrů
• 2102 = Neplatný požadavek – neshoda kódování vstupních dat
• 4000 = Interní chyba
• 4001 = Interní výjimka
• 5000 = Fatální chyba
• 5001 = Interní chyba autentizace
• 5003 = Mimo provoz

---

Aktivace WAPI

Než začnete WAPI používat, musíte ho aktivovat. Postupujte takto:

1. Přihlaste se do administrace WEDOS Global ⧉.
2. V levém menu vyberte WAPI.
3. Ve formuláři Nastavení WAPI zadejte následující údaje a potvrďte tlačítkem Nastavit :
   • Povolené IP adresy: Seznam IP adres oddělených čárkou (IPv4 i IPv6, podporován je zápis CIDR), ze kterých se váš systém připojuje k WAPI.
   • Režim notifikací: Způsob přijímání notifikací o průběhu asynchronních požadavků.
   • Preferovaný protokol: Toto nastavení platí pouze pro systémové notifikace. Odpovědi používají stejný formát jako požadavky.
4. Ve formuláři Nastavení hesla zadejte heslo k WAPI (dvakrát kvůli potvrzení) a klikněte na tlačítko Nastavit .

Nastavení se projeví do 30 minut.

---

Integrace WAPI do vašeho systému

Po aktivaci WAPI je pro integraci do vašeho systému potřeba:

• Připravit skript pro připojení k API
• Odeslat požadavek
• Přijmout a zpracovat odpověď
• Přijmout a zpracovat notifikaci

Připojení k WAPI

Pro připojení vašeho systému k WAPI budete potřebovat:

• Přihlašovací e-mail WEDOS a heslo k WAPI
• Adresu WAPI (podle formátu):
  • XML:https://api.wedos.com/wapi/xml
  • JSON:https://api.wedos.com/wapi/json

WAPI používá jediný autentizační řetězec, kterým je SHA-1 hash řetězce složeného z uživatelského jména, SHA-1 hashe hesla pro WAPI a aktuální hodiny (00-23). Časové pásmo je Europe/Prague (UTC+1 CET, případně UTC+2 CET při letním čase). Konkrétní příklad najdete v kódu níže.

Následující šablona ukazuje připojení k WAPI pomocí PHP skriptu:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'your@login.tld'; 
$wpass = 'your-WAPI-password'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'request name',
  'data' => ['request data'],
  'clTRID' => 'request identifier',
  'test' => '1 (if you only want to test the request)'
  ]
];

$post = json_encode($input);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_TIMEOUT,60);
curl_setopt($ch,CURLOPT_POST,true);
curl_setopt($ch,CURLOPT_POSTFIELDS, 'request=' . urlencode($post));
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
curl_close($ch);
?>

Požadavek WAPI

Požadavek WAPI se skládá z následujících dat:

• test: Příznak testovacího režimu, nepovinný. Pokud do požadavku vložíte prvek test s hodnotou 1, WAPI pouze zkontroluje příkaz, ale neprovede v systému žádné změny.
• user: Přihlašovací jméno (e-mail) vašeho zákaznického účtu WEDOS, povinný.
• auth: Autorizační řetězec, povinný. Jde o SHA-1 otisk řetězce složeného z uživatelského jména, SHA-1 otisku hesla k WAPI a aktuální hodiny (00-23). Časovou zónou je Europe/Prague (UTC+1 CET, případně UTC+2 CET s letním časem). Konkrétní příklad najdete v kódu níže.
• příkaz: Vlastní požadavek WAPI. Povinný.
• clTRID: Identifikátor požadavku, nepovinný. Do tohoto prvku můžete vložit libovolný řetězec jako identifikátor, který WAPI vrátí v odpovědi.
• data: Datová část požadavku. Nepovinná.

Šablona požadavku ve formátu JSON:

{
  "request":
  {
    "user": "your@login.tld",
    "auth": "auth-string",
    "command": "request-name",
    "data":
    {
      data požadavku
    }
    "clTRID": "request-id (optional)",
  }
}

Odpověď WAPI

Odpověď se skládá z následujících dat:

• kód: Návratová hodnota daného požadavku. Více informací o těchto kódech najdete v sekci Návratové kódy a v dokumentaci konkrétních příkazů.
• result: Popis návratového kódu.
• timestamp: Čas provedení příkazu ve formátu UNIX.
• clTRID: Identifikátor požadavku od klienta.
• svTRID: Identifikátor požadavku od serveru.
• příkaz: Požadavek WAPI.
• data: Vrácená data. Při chybě požadavku žádná.
• test: Obsaženo v odpovědích na testovací požadavky.

Šablona odpovědi ve formátu JSON:

{
  "response": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "request-name"
  }
}

Notifikace

Asynchronní požadavky nelze provést okamžitě. Průběh a výsledek takových operací můžete sledovat prostřednictvím notifikací. Synchronní požadavky notifikace nepoužívají.

Pokud WAPI nemůže operaci dokončit okamžitě, vrátí v odpovědi Request pending (1001). Po dokončení operace (u složitějších akcí jednotlivých kroků) vytvoří notifikaci, která je podobná klasické odpovědi. Notifikaci můžete přiřadit k odpovídajícímu požadavku pomocí parametrů clTRID nebo svTRID.

Data notifikací jsou vždy kódována v UTF-8.

Notifikace můžete přijímat následujícími způsoby (podle nastavení):

• Pomocí fronty POLL.
• Odesláním na zadanou e-mailovou adresu.
• Prostřednictvím protokolu HTTP (nebo HTTPS) na vámi zadanou URL adresu metodou POST v parametru request. Za úspěch se považuje odpověď HTTP s návratovým kódem 200. Pokud doručení selže, systém se pokusí notifikaci doručit znovu v několikaminutových intervalech.

Následuje šablona notifikace JSON:

{
  "notify": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "svTRID": "server request id",
    "command": "request-name",
    "ID": "numerical id"
  }
}

---

Základní požadavky

Mezi základní požadavky patří ping, ping-async, a příkazy pro práci s frontou POLL poll-req a poll-ack.

ping

Požadavek ping slouží k otestování funkčnosti WAPI – například přihlašovacích údajů, IP adresy nebo kódu.

Návratové hodnoty jsou:

• 1000 – OK

Šablona požadavku JSON:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping",
    "clTRID": "user request id"
  }
}

Šablona odpovědi JSON:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping"
  }
}

ping-async

Požadavek ping-async testuje funkčnost notifikací WAPI.

Návratové hodnoty jsou:

• 1000 – OK
• 1001 – Čekání na požadavek

Šablona požadavku JSON:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping-async",
    "clTRID": "user request id"
  }
}

Šablona odpovědi JSON:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async"
  }
}

Šablona notifikace JSON:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async",
    "id": "poll queue id",
    "data": {
      "round": "attempt number",
      "time": "time",
      "done": 1
    }
  }
}

poll-req a poll-ack

Notifikace z fronty POLL můžete přijímat kombinací poll-req a poll-ack :

1. Použijte poll-req pro stažení nejstarší dostupné notifikace.
2. Pomocí příkazu poll-ack označíte notifikaci jako přečtenou a zpřístupníte novější, dokud se fronta nevyprázdní.

Návratové hodnoty pro poll-req jsou:

• 1000 – notifikace přijata
• 1003 – ve frontě není žádná nepřečtená notifikace
• 2150 – notifikace ve frontě POLL jsou pro tento účet zakázány

JSON poll-req šablona požadavku:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-req",
    "clTRID": "user request id"
  }
}

JSON poll-req šablona odpovědi (notifikace k dispozici):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF time",
        "clTRID": "request user id",
        "svTRID": "request server id",
        "command": "request name",
        "id": "poll queue id"
      }
    }
  }
}

JSON poll-req šablona odpovědi (prázdná fronta notifikací):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req"
  }
}

Uveďte následující parametry v požadavku poll-ack :

• id – ID aktuální notifikace ve frontě POLL

Návratové hodnoty pro poll-ack jsou:

• 1002 – notifikace označena jako přečtená
• 2151 – notifikace nenalezena

JSON poll-ack :

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-ack",
    "clTRID": "user request id",
    "data": {
      "id": “poll notification id”
    }
  }
}

JSON poll-ack odpověď:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-ack"
  }
}

---

Řešení nejčastějších problémů

Mezi časté problémy s WAPI patří:

• Selhání autentizace požadavků

---

FAQ

Pomohl vám tento návod?

Vaše hodnocení nám pomáhá návody zlepšovat.

AnoNe

Chcete nám k návodu něco napsat? (nepovinné)

Vzkaz si přečte redakce návodů, ale neodpovídá na něj. Když potřebujete poradit, zeptejte se na komunitním webu Help. Nepište sem hesla ani osobní údaje.

Tohle pole nevyplňujte