WAPI – Manuál

V tomto článku sa dozviete:

• Ako funguje WAPI
  • 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 integrovať WAPI do vášho systému
• Základné požiadavky na otestovanie funkcií WAPI
• Riešenie bežný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 je buď synchrónny (odpoveď sa zvyčajne spracuje v priebehu niekoľkých sekúnd od prijatia požiadavky) alebo asynchrónne (niektoré odpovede môžu trvať dlhšie; proces je sledovaný prostredníctvom notifikácií).
• Údaje sa odovzdávajú cez HTTPS protokol pomocou POST metódu v parametri requestu; kódovanie dát je UTF-8.
• Podporované formáty zahŕňajú 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

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

• Domény
• Kontakty domény
• Kreditný účet

Obmedzenia WAPI

Ako ochranu proti zneužitiu uplatňuje 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 odmieta ďalšie požiadavky až do vypršania časového limitu.
• 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 neautorizovanej IP adresy, nesprávny vstup, chýbajúce alebo nesprávne parametre, neznáme príkazy, príkazy vedúce k akejkoľvek chybe alebo akákoľvek požiadavka nad rámec ostatných obmedzení) spôsobí zablokovanie IP adresy na 1 minútu za každú neplatnú požiadavku presahujúcu 10. S každou ďalšou neplatnou požiadavkou systém predlžuje dobu blokovania.

Synchrónne a asynchrónne požiadavky

Väčšina požiadaviek vykonávaných cez WAPI je synchrónna – požiadavku odošlete 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 takých prípadoch WAPI nevracia konečný výsledok, ale iba informáciu o prijatí požiadavky. Systém vám potom zašle informácie o priebehu a konečnom výsledku formou notifikácie.

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 len 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 = Chyba autentifikácie
• 2051 = Prístup z tejto IP adresy nie je povolený
• 2052 = IP adresa je dočasne zablokovaná pre príliš veľa neúspešných požiadaviek
• 2100 = Chýba povinný parameter
• 2101 = Nesúlad parametrov
• 2102 = Neplatná požiadavka – nesúlad kódovania vstupných údajov
• 4000 = Interná chyba
• 4001 = Interná výnimka
• 5000 = Fatálna chyba
• 5001 = Interná chyba autentifikácie
• 5003 = Mimo prevádzky

---

Aktivovať WAPI

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

1. Prihláste sa do Administrácia WEDOS Global ⧉.
2. V ľavom paneli vyberte WAPI.
3. V Nastavenie WAPI formulári zadajte nasledujúce údaje a potvrďte pomocou Nastaviť tlačidlo:
   • Povolené IP adresy: Zoznam IP adries (IPv4 aj IPv6) oddelených čiarkou, z ktorých sa váš systém pripája k WAPI.
   • Režim upozornení: Spôsob prijímania oznámení 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. V Nastavenia hesla formulári zadajte heslo pre WAPI (dvakrát pre potvrdenie) a kliknite na Nastaviť tlačidlo.

Nastavenie sa prejaví do 30 minút.

---

Integrujte WAPI do svojho systému

Na integráciu WAPI do svojho systému po jeho aktivácii potrebujete:

• Vytvorenie skriptu na pripojenie k API
• Odoslať požiadavku
• Prijatie a spracovanie odpovede
• Prijatie a spracovanie notifikácie

Pripojiť sa k WAPI

Na pripojenie svojho systému k WAPI budete potrebovať:

• Váš prihlasovací e-mail WEDOS a heslo pre WAPI
• URL adresa WAPI (podľa formátu):
  • XML:https://api.wedos.com/wapi/xml
  • JSON:https://api.wedos.com/wapi/json

WAPI prijíma 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 WAPI a aktuálnej hodiny (00-23). Časová zóna 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 týchto údajov:

• test: Príznak testovacieho režimu, voliteľný. Ak do požiadavky zaradíte prvok test s hodnotou 1, WAPI príkaz iba skontroluje, ale nevykoná v systéme žiadne zmeny.
• používateľ: Prihlasovacie meno (e-mail) vášho zákazníckeho účtu WEDOS, povinné.
• auth: Autorizačný reťazec, povinný. Je to SHA-1 hash reťazca zloženého z používateľského mena, SHA-1 hashu hesla k 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.
• príkaz: Samotná požiadavka WAPI. Povinné.
• clTRID: ID požiadavky, voliteľné. Do tohto prvku môžete vložiť ľubovoľný reťazec ako identifikátor, ktorý WAPI vráti v odpovedi.
• dáta: Dátová časť požiadavky. Voliteľné.

Nasleduje šablóna JSON požiadavky:

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

Odpoveď WAPI

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

• kód: Návratová hodnota pre danú požiadavku. Viac informácií o týchto kódoch nájdete v Návratové kódy sekciu a dokumentáciu konkrétneho príkazu.
• výsledok: Popis návratového kódu.
• timestamp: Čas vykonania príkazu vo formáte UNIX.
• clTRID: Identifikátor požiadavky klienta.
• svTRID: Identifikátor požiadavky servera.
• príkaz: Požiadavka WAPI.
• dáta: Návratové údaje. Pri neúspešnej požiadavke žiadne.
• test: Súčasť odpovedí na testovacie požiadavky.

Nasleduje šablóna JSON odpovede:

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

Upozornenia

Asynchrónne požiadavky nie je možné vykonať okamžite. Priebeh a výsledok takých 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 priradíte k zodpovedajúcej požiadavke pomocou parametrov clTRID alebo svTRID.

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

Notifikácie môžete prijímať týmito spôsobmi (podľa nastavenia):

• S využitím fronty POLL.
• Odoslať na zadanú e-mailovú adresu.
• Cez protokol HTTP (alebo HTTPS) na vami zadanú URL adresu metódou POST v parametri request. Za úspech sa považuje HTTP odpoveď 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 JSON notifikácie:

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

---

Základné požiadavky

Základné požiadavky zahŕňajú ping, ping-async, a príkazy na prácu s frontou POLL poll-req a poll-ack.

ping

Tento ping požiadavka 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 JSON požiadavky:

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

Šablóna JSON odpovede:

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

ping-async

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

Návratové hodnoty sú:

• 1000 – OK
• 1001 – Čaká sa na požiadavku

Šablóna JSON požiadavky:

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

Šablóna JSON odpovede:

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

Šablóna JSON notifikácie:

{
  "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 príkazy:

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

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

• 1000 – oznámenie prijaté
• 1003 – vo fronte nie je žiadne neprečítané oznámenie
• 2150 – oznámenia vo fronte poll sú pre tento účet vypnuté

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"
  }
}

Do poll-ack požiadavka:

• id – ID aktuálnej poll notifikácie

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

• 1002 – oznámenie označené ako prečítané
• 2151 – oznámenie sa nenašlo

JSON poll-ack požiadavka:

{
  "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 bežných problémov

Medzi bežné problémy s WAPI patria:

• Neúspešná autentifikácia požiadaviek

---

FAQ