WAPI – príručka

V tomto článku sa dozviete:

• Ako WAPI funguje
  • Podporované služby
  • Obmedzenia požiadaviek
  • Synchrónne a asynchrónne požiadavky
  • Návratové kódy
• Ako aktivovať WAPI v administrácii WEDOS Global
• Ako WAPI integrovať do vášho systému
• Základné požiadavky na otestovanie funkcií WAPI
• Riešenie najčastejších problémov
• Často kladené otázky

---

WEDOS API (WAPI)

WEDOS API, skrátene WAPI, slúži na správu služieb WEDOS priamo z vášho systému pomocou požiadaviek a odpovedí.

• Komunikácia prebieha buď synchrónna (odpoveď sa spracuje zvyčajne do niekoľkých sekúnd od prijatia požiadavky), alebo asynchrónna (niektoré odpovede môžu trvať dlhšie; priebeh sledujete pomocou notifikácií).
• Dáta sa odovzdávajú protokolom HTTPS metódou POST v parametri request; kódovanie dát je UTF-8.
• Podporované formáty sú XML a JSON.

Podporované služby

WAPI aktuálne podporuje nasledujúce služby WEDOS Global:

• Členovia WEDOS Global
• WEDOS Protection
• WEDOS DNS a NSSET

Ďalej máte prístup k službám registrátora domén WEDOS:

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

Obmedzenia WAPI

Ako ochrana proti zneužitiu platia pre WAPI nasledujúce obmedzenia:

• Jeden používateľský účet môže odoslať maximálne 1000 požiadaviek za hodinu. Platí to pre všetky typy požiadaviek. Po dosiahnutí tohto limitu WAPI ďalšie požiadavky odmieta, kým neuplynie časový limit.
• Jeden používateľský účet môže odoslať maximálne 100 požiadaviek na dostupnosť domény za hodinu. Platí to pre požiadavky domain-check, domain-create a domain-transfer-check.
• Opakované neplatné požiadavky (zlyhanie autorizácie, prístup z nepovolenej IP adresy, chybný vstup, chýbajúce alebo nesprávne parametre, neznáme príkazy, príkazy končiace chybou alebo akákoľvek požiadavka nad rámec ďalších obmedzení) spôsobia zablokovanie IP adresy na 1 minútu za každú neplatnú požiadavku nad 10. S každou ďalšou neplatnou požiadavkou systém dobu blokovania predlžuje.

Synchrónne a asynchrónne požiadavky

Väčšina požiadaviek vykonávaných cez WAPI je synchrónnych – odošlete požiadavku a výsledok zvyčajne dostanete do niekoľkých sekúnd.

Niektoré požiadavky sú asynchrónne – ich spracovanie môže trvať veľmi dlho (aj hodiny alebo dni). V takom prípade WAPI nevracia konečný výsledok, ale iba informáciu o prijatí požiadavky. Informácie o priebehu a konečnom výsledku vám potom systém posiela formou notifikácií.

Návratové kódy

Návratové kódy udávajú stav odpovede WAPI. Niektoré kódy sú špecifické pre konkrétnu požiadavku a nájdete ich v príslušnej dokumentácii WAPI; nižšie uvedený zoznam platí pre všetky požiadavky.

• 1000 = OK
• 2000 = Chyba pri spracovaní požiadavky
• 2001 = Neplatná požiadavka – chýba povinný parameter: user
• 2002 = Neplatná požiadavka – chýba povinný parameter: auth
• 2003 = Neplatná požiadavka – chýba povinný parameter: command
• 2004 = Neplatná požiadavka – povolený je iba jeden prvok data
• 2005 = Neplatná požiadavka – parameter clTRID je príliš dlhý
• 2006 = Prekročený limit požiadaviek
• 2007 = Neplatná požiadavka – prekročená maximálna veľkosť požiadavky
• 2008 = Neplatná požiadavka – požiadavka je príliš zložitá
• 2009 = Neplatná požiadavka – požiadavka je prázdna
• 2010 = Neznámy príkaz
• 2011 = Príkaz je zakázaný
• 2050 = Zlyhanie autentizácie
• 2051 = Prístup z tejto IP adresy nie je povolený
• 2052 = IP adresa je dočasne zablokovaná pre priveľa chybných požiadaviek
• 2100 = Chýba povinný parameter
• 2101 = Nezhoda parametrov
• 2102 = Neplatná požiadavka – nezhoda kódovania vstupných dát
• 4000 = Interná chyba
• 4001 = Interná výnimka
• 5000 = Fatálna chyba
• 5001 = Interná chyba autentizácie
• 5003 = Mimo prevádzky

---

Aktivácia WAPI

Skôr než začnete WAPI používať, musíte ho aktivovať. Postupujte takto:

1. Prihláste sa do administrácie WEDOS Global ⧉.
2. V ľavom menu vyberte WAPI.
3. Vo formulári Nastavenie WAPI zadajte nasledujúce údaje a potvrďte tlačidlom Nastaviť :
   • Povolené IP adresy: Zoznam IP adries oddelených čiarkou (IPv4 aj IPv6, podporovaný je zápis CIDR), z ktorých sa váš systém pripája k WAPI.
   • Režim notifikácií: Spôsob prijímania notifikácií o priebehu asynchrónnych požiadaviek.
   • Preferovaný protokol: Toto nastavenie platí iba pre systémové notifikácie. Odpovede používajú rovnaký formát ako požiadavky.
4. Vo formulári Nastavenie hesla zadajte heslo k WAPI (dvakrát kvôli potvrdeniu) a kliknite na tlačidlo Nastaviť .

Nastavenie sa prejaví do 30 minút.

---

Integrácia WAPI do vášho systému

Po aktivácii WAPI je na integráciu do vášho systému potrebné:

• Pripraviť skript na pripojenie k API
• Odoslať požiadavku
• Prijať a spracovať odpoveď
• Prijať a spracovať notifikáciu

Pripojenie k WAPI

Na pripojenie vášho systému k WAPI budete potrebovať:

• Prihlasovací e-mail WEDOS a heslo k WAPI
• Adresu WAPI (podľa formátu):
  • XML:https://api.wedos.com/wapi/xml
  • JSON:https://api.wedos.com/wapi/json

WAPI používa jediný autentizačný reťazec, ktorým je SHA-1 hash reťazca zloženého z používateľského mena, SHA-1 hashu hesla pre WAPI a aktuálnej hodiny (00-23). Časové pásmo je Europe/Prague (UTC+1 CET, prípadne UTC+2 CET pri letnom čase). Konkrétny príklad nájdete v kóde nižšie.

Nasledujúca šablóna ukazuje pripojenie k WAPI pomocou 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žiadavka WAPI

Požiadavka WAPI sa skladá z nasledujúcich dát:

• test: Príznak testovacieho režimu, nepovinný. Ak do požiadavky vložíte prvok test s hodnotou 1, WAPI iba skontroluje príkaz, ale nevykoná v systéme žiadne zmeny.
• user: Prihlasovacie meno (e-mail) vášho zákazníckeho účtu WEDOS, povinný.
• auth: Autorizačný reťazec, povinný. Ide o SHA-1 odtlačok reťazca zloženého z používateľského mena, SHA-1 odtlačku hesla k WAPI a aktuálnej hodiny (00-23). Časovou zónou je Europe/Prague (UTC+1 CET, prípadne UTC+2 CET s letným časom). Konkrétny príklad nájdete v kóde nižšie.
• príkaz: Vlastná požiadavka WAPI. Povinný.
• clTRID: Identifikátor požiadavky, nepovinný. Do tohto prvku môžete vložiť ľubovoľný reťazec ako identifikátor, ktorý WAPI vráti v odpovedi.
• data: Dátová časť požiadavky. Nepovinná.

Šablóna požiadavky vo formáte JSON:

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

Odpoveď WAPI

Odpoveď sa skladá z nasledujúcich dát:

• kód: Návratová hodnota danej požiadavky. Viac informácií o týchto kódoch nájdete v sekcii Návratové kódy a v dokumentácii konkrétnych príkazov.
• result: Popis návratového kódu.
• timestamp: Čas vykonania príkazu vo formáte UNIX.
• clTRID: Identifikátor požiadavky od klienta.
• svTRID: Identifikátor požiadavky od servera.
• príkaz: Požiadavka WAPI.
• data: Vrátené dáta. Pri chybe požiadavky žiadne.
• test: Obsiahnuté v odpovediach na testovacie požiadavky.

Šablóna odpovede vo formáte JSON:

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

Notifikácie

Asynchrónne požiadavky nie je možné vykonať okamžite. Priebeh a výsledok takýchto operácií môžete sledovať prostredníctvom notifikácií. Synchrónne požiadavky notifikácie nepoužívajú.

Ak WAPI nemôže operáciu dokončiť okamžite, vráti v odpovedi Request pending (1001). Po dokončení operácie (pri zložitejších akciách jednotlivých krokov) vytvorí notifikáciu, ktorá je podobná klasickej odpovedi. Notifikáciu môžete priradiť k zodpovedajúcej požiadavke pomocou parametrov clTRID alebo svTRID.

Dáta notifikácií sú vždy kódované v UTF-8.

Notifikácie môžete prijímať nasledujúcimi spôsobmi (podľa nastavenia):

• Pomocou fronty POLL.
• Odoslaním na zadanú e-mailovú adresu.
• Prostredníctvom protokolu HTTP (alebo HTTPS) na vami zadanú URL adresu metódou POST v parametri request. Za úspech sa považuje odpoveď HTTP s návratovým kódom 200. Ak doručenie zlyhá, systém sa pokúsi notifikáciu doručiť znova v niekoľkominútových intervaloch.

Nasleduje šablóna notifikácie JSON:

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

---

Základné požiadavky

Medzi základné požiadavky patria ping, ping-async, a príkazy na prácu s frontou POLL poll-req a poll-ack.

ping

Požiadavka ping slúži na otestovanie funkčnosti WAPI – napríklad prihlasovacích údajov, IP adresy alebo kódu.

Návratové hodnoty sú:

• 1000 – OK

Šablóna požiadavky JSON:

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

Šablóna odpovede JSON:

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

ping-async

Požiadavka ping-async testuje funkčnosť notifikácií WAPI.

Návratové hodnoty sú:

• 1000 – OK
• 1001 – Čakanie na požiadavku

Šablóna požiadavky JSON:

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

Šablóna odpovede JSON:

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

Šablóna notifikácie 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

Notifikácie z fronty POLL môžete prijímať kombináciou poll-req a poll-ack :

1. Použite poll-req na stiahnutie najstaršej dostupnej notifikácie.
2. Pomocou príkazu poll-ack označíte notifikáciu ako prečítanú a sprístupníte novšie, kým sa fronta nevyprázdni.

Návratové hodnoty pre poll-req sú:

• 1000 – notifikácia prijatá
• 1003 – vo fronte nie je žiadna neprečítaná notifikácia
• 2150 – notifikácie vo fronte POLL sú pre tento účet zakázané

JSON poll-req šablóna požiadavky:

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

JSON poll-req šablóna odpovede (notifikácia k dispozícii):

{
  "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 šablóna odpovede (prázdna fronta notifikácií):

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

Uveďte nasledujúce parametre v požiadavke poll-ack :

• id – ID aktuálnej notifikácie vo fronte POLL

Návratové hodnoty pre poll-ack sú:

• 1002 – notifikácia označená ako prečítaná
• 2151 – notifikácia nenájdená

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 odpoveď:

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

---

Riešenie najčastejších problémov

Medzi časté problémy s WAPI patria:

• Zlyhanie autentizácie požiadaviek

---

FAQ

Pomohol vám tento článok?

Vaše hodnotenie nám pomáha zlepšovať naše články.

ÁnoNie

Chceli by ste nám k tomuto článku niečo napísať? (nepovinné)

Vašu správu si prečíta tím tvorcov dokumentácie, ale neodpovedá na ňu. Ak potrebujete poradiť, kontaktujte nás pomocou kontaktného formulára. Nezadávajte sem heslá ani osobné údaje.

Toto pole nevypĺňajte