WAPI – Príručka

V tomto článku sa dozviete:

• Ako WAPI funguje a na čo slúži
• Ako aktivovať WAPI v zákazníckej administrácii
• Ako prebieha komunikácia a autentifikácia
• Jak stránkovat a hledat v seznamech
• Základné príkazy
• Zoznam návratových kódov
• Slovníček pojmov

---

WEDOS API

WEDOS API, teda WAPI, slúži na ovládanie služieb priamo z Vášho informačného systému. 

Podmienkou použitia rozhrania je využívanie zálohového účtu WEDOS, z ktorého systém odpočítava platby za registrácie, predĺženia, prevody a ďalšie účtované poplatky.

WAPI v súčasnosti umožňuje správu:

• Zálohového účtu ⧉ (account-* a credit-*)
• Domén ⧉ (domains-* a domain-*)
• Doménových kontaktov ⧉ (contact-*)
• NSSETu ⧉ (nsset-*)
• DNS ⧉ (dns-*)
• Oprávnených používateľov WEDOS Global ⧉ (wg-members-*)
• WEDOS Protection ⧉ (wgp-services-* a wgp-domain-*)

Obmedzenia WAPI

Ako ochranu pred zneužívaním uplatňuje WAPI tieto obmedzenia:

• Cez jeden používateľský účet môžete odoslať max. 1000 požiadaviek za hodinu. Týka sa to všetkých požiadaviek všetkých typov, po dosiahnutí tohto limitu WAPI ďalšie požiadavky odmieta až do uplynutia časového limitu.
• Jeden používateľský účet smie zadať max. 100 požiadaviek na dostupnosť domény za hodinu. Týka sa to príkazov domain-check, domain-create a domain-transfer-check.
• Opakované zasielanie neplatných požiadaviek (zlyhanie autorizácie, prístup z nepovolenej IP adresy, chybný vstup, chýbajúce alebo nesprávne parametre, neznámy príkaz, príkazy končiace akoukoľvek chybou alebo akákoľvek požiadavka nad rámec ostatných obmedzení) spôsobí pri prekročení 10 neplatných požiadaviek blokáciu IP adresy na 1 minútu za každú neplatnú požiadavku. S každou ďalšou chybnou požiadavkou systém dobu blokovania predlžuje.

Synchrónne a asynchrónne operácie

Väčšina príkazov vykonávaných cez WAPI je synchrónna – pošlete príkaz a spravidla v priebehu niekoľkých sekúnd sa dozviete výsledok. 

Niektoré operácie sú asynchrónne, vybavenie takého príkazu teda môže trvať veľmi dlho (aj hodiny alebo dni). WAPI preto nevráti konečný výsledok, ale iba informáciu o prijatí príkazu. Informácie o priebehu a finálny výsledok Vám potom systém zasiela formou notifikácií.

Logovanie

Log požiadaviek nájdete v zákazníckej administrácii týmito krokmi:

1. Prihláste sa do zákazníckej administrácie ⧉.
2. V hornom menu vyberte My account Customer.
3. V ľavom menu vyberte WAPI requests.

---

Aktivácia WAPI v zákazníckej administrácii

Skôr než začnete WAPI používať, aktivujte ho v zákazníckej administrácii týmito krokmi:

1. Prihláste sa do zákazníckej administrácie ⧉.
2. V hornom menu vyberte My account Customer.
3. V ľavom menu vyberte WAPI interface.
4. Nastavte povolené IP adresy (IPv4 alebo IPv6, podporuje CIDR), spôsob notifikácií, preferovaný protokol a heslo.
5. Nastavenie potvrďte tlačidlami Set.

---

Komunikácia a autentifikácia

Komunikácia s rozhraním WAPI prebieha cez protokol HTTPS. Dáta sa odovzdávajú metódou POST v parametri request vo formáte XML alebo JSON. Základný tvar príkazu aj odpovede je pre všetky príkazy rovnaký. Kódovanie dát je UTF-8.

URL adresy rozhrania:

• XML: https://api.wedos.com/wapi/xml
• JSON: https://api.wedos.com/wapi/json

Štruktúra požiadavky

Požiadavka pozostáva z týchto údajov:

• user: Používateľské meno (e-mail) Vášho zákazníckeho účtu, povinný parameter.
• auth: Autorizačný reťazec, povinný parameter. Ide o sha1 hash reťazca zloženého z používateľského mena, sha1 hashu hesla WAPI a aktuálnej hodiny (00-23). Časové pásmo je Europe/Prague (zimný čas UTC+1 SEČ, letný čas UTC+2 SELČ). Konkrétny príklad pozri v kóde nižšie.
• command: Samotný príkaz WAPI. Povinný parameter.
• clTRID: ID požiadavky, nepovinný parameter. Do tohto elementu môžete vložiť akýkoľvek reťazec ako identifikátor, ktorý WAPI vráti v odpovedi.
• data: Dátová časť príkazu. Nepovinný parameter.
• test: Príznak testovacieho režimu, nepovinný parameter. Ak do príkazu vložíte element test s hodnotou 1, WAPI Váš príkaz iba skontroluje, ale nebude vykonávať žiadne zmeny.

Šablóna požiadavky (JSON) je teda:

{
  "request":
  {
    "user": "váš@login.tld",
    "auth": "autorizačný reťazec",
    "command": "názov požiadavky",
    "data":
    {
      údaje požiadavky
    }
    "clTRID": "identifikátor požiadavky (nepovinné)",
    "test": "1 (ak chcete požiadavku iba otestovať, nepovinné)"
  }
}

Kompletný príklad použitia v PHP (dátový formát JSON) potom môže byť:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'váš@login.tld'; 
$wpass = 'vaše heslo k WAPI'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'názov požiadavky',
  'data' => ['pole údajov požiadavky'],
  'clTRID' => 'identifikátor požiadavky (nepovinné)',
  'test' => '1 (ak chcete požiadavku iba otestovať)'
  ]
];

$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);
?>

Štruktúra odpovede

Odpoveď pozostáva z týchto údajov:

• code: Návratová hodnota príkazu. Viac informácií nájdete v kapitole Návratové kódy.
• result: Textový popis návratového kódu.
• timestamp: Čas vykonania príkazu vo formáte UNIX.
• clTRID: Identifikátor príkazu zo strany klienta.
• svTRID: Identifikátor príkazu na strane servera.
• command: Príkaz WAPI.
• data: Návratové hodnoty. Ak príkaz zlyhá, dáta nevracia.
• test: Vkladá sa pri odpovedi na príkazy obsahujúce aj tento príznak.

Vzorová odpoveď vo formáte JSON vyzerá napríklad takto:

{
  "response":
  {
    "code": "1000",
    "result": "ok",
    "timestamp": "1286356644",
    "svTRID": "1286356644.0246.21616",
    "command": "domain-create",
    "data": 		
    {
      "num": "1311000863",
      "expiration": "2011-10-06"
    },
    "test": "1"
  }
}

Stránkování a hledání v seznamech

Seznamové příkazy domains-list a dns-rows-list mají nepovinné parametry pro hledání a stránkování. Když je nezadáte, WAPI vrátí odpověď stejně jako dosud, tedy celý seznam.

Parametry v části data požadavku:

• search: Hledaný text, bez rozlišení velikosti písmen. U domains-list se hledá v názvu domény, u dns-rows-list v názvu nebo datech záznamu.
• page: Číslo stránky od 1. Výchozí hodnota je 1.
• page_limit: Počet položek na stránku, nejvýše 1000 (větší hodnotu WAPI sníží na 1000). Když ho nezadáte nebo zadáte 0, WAPI vrátí všechny položky.

Príkaz dns-rows-list má navíc tyto filtry:

• row_name: Přesný název záznamu. Hodnota @ znamená záznam přímo na doméně.
• rdtype: Typ záznamu (A, AAAA, MX, TXT…), na velikosti písmen nezáleží.

Když zadáte kterýkoli z těchto parametrů, WAPI vrátí seznam jako pole (u domains-list v položce domain, u dns-rows-list v položce row) a v části data odpovědi doplní:

• total: Celkový počet položek po použití filtrů.
• page: Číslo vrácené stránky.
• page_limit: Použitý počet položek na stránku (0 znamená všechny).

Na co dát pozor:

• Stránka za koncem seznamu vrátí prázdný seznam s položkou total, ne chybu.
• Neplatnou hodnotu page alebo page_limit (text, záporné číslo) WAPI neodmítne, ale nahradí ji výchozí hodnotou: page 1, page_limit 0, tedy všechny položky.
• Pole místo hodnoty v page alebo page_limit vrátí chybu 2101.
• Príkaz dns-domains-list vrací total (jako řetězec), page a page_limit vždy. Když page_limit nezadáte nebo zadáte 0, použije 1000.

JSON príkaz domains-list (aktivní domény obsahující „example“, první stránka po dvou doménách), podrobný popis v dokumentaci příkazu domains-list ⧉:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizačný reťazec",
    "command": "domains-list",
    "clTRID": "vlastný id kód",
    "data": {
      "status": "active",
      "search": "example",
      "page": 1,
      "page_limit": 2
    }
  }
}

JSON príkaz dns-rows-list (záznamy typu A domény example.cz, první stránka po 50 záznamech), podrobný popis v dokumentaci příkazu dns-rows-list ⧉:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizačný reťazec",
    "command": "dns-rows-list",
    "clTRID": "vlastný id kód",
    "data": {
      "domain": "example.cz",
      "rdtype": "A",
      "page": 1,
      "page_limit": 50
    }
  }
}

Notifikácia

Asynchrónne operácie nemožno 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 nedokáže operáciu dokončiť ihneď, v odpovedi vráti Request pending (1001). Po dokončení operácie (pri komplikovanejších akciách jednotlivých krokov) vytvorí notifikáciu, ktorá je obdobou klasickej odpovede. Notifikáciu môžete príslušnej požiadavke priradiť podľa parametrov clTRID alebo svTRID.

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

Notifikácie môžete získavať týmito spôsobmi (podľa nastavenia pri aktivácii):

• Cez POLL frontu.
• Zaslaním na uvedenú e-mailovú adresu.
• Cez protokol HTTP (alebo HTTPS) na Vami určenú URL adresu metódou POST v parametri request. Za korektné doručenie sa považuje HTTP odpoveď s návratovým kódom 200. Ak sa doručiť nepodarí, náš systém sa bude v niekoľkominútových intervaloch pokúšať o doručenie znova.

Vzorová notifikácia vo formáte JSON vyzerá napríklad takto:

{
  "notify": {
    "code": 1000,
    "result": "OK",
    "timestamp": 1286957932,
    "clTRID": "AvrX87Kqk6h3",
    "svTRID": "1286957874.1271.15706",
    "command": "ping-async",
    "ID": 2691
  }
}

Systémové notifikácie

Systémové notifikácie odosielajú informácie o relevantných udalostiach, v súčasnosti iba o prevode domény inam. Ak máte pri účte aktívne WAPI, systém takúto informáciu odošle prostredníctvom notifikácie podobne ako pri asynchrónnom príkaze.

Nastavenie protokolu, v ktorom WAPI systémové notifikácie odosiela, vykonajte podľa kapitoly Aktivácia WAPI v zákazníckej administrácii. Táto voľba funguje pre notifikácie odosielané na e-mail alebo URL adresu. V prípade stiahnutia z POLL fronty je odpoveď v rovnakom tvare ako príkaz.

Štruktúra je rovnaká ako pri klasickej notifikácii, príkaz (command) je vždy system-notify. V uzle data nájdete podrobnejšie informácie.

---

Základné príkazy

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

ping

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

Návratové hodnoty sú:

• 1000 – OK

JSON príkaz:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizačný reťazec",
    "command": "ping",
    "clTRID": "vlastný id kód"
  }
}

JSON odpoveď:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF čas",
    "clTRID": "vlastný id kód",
    "svTRID": "id kód servera",
    "command": "ping"
  }
}

ping-async

Príkaz ping-async testuje funkčnosť notifikácií WAPI.

Návratové hodnoty sú:

• 1000 OK
• 1001 Čakanie na príkaz

JSON príkaz:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizačný reťazec",
    "command": "ping",
    "clTRID": "vlastný id kód"
  }
}

JSON odpoveď:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF čas",
    "clTRID": "vlastný id kód",
    "svTRID": "id kód servera",
    "command": "ping"
  }
}

JSON notifikácia:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF čas",
    "clTRID": "vlastný id kód",
    "svTRID": "id kód servera",
    "command": "ping-async",
    "id": "id pre POLL frontu",
    "data": {
      "round": "číslo pokusu",
      "time": "čas",
      "done": 1
    }
  }
}

poll-req a poll-ack

Získavanie notifikácií z POLL fronty vykonávate kombináciou príkazov poll-req a poll-ack: 

1. Príkazom poll-req stiahnete najstaršiu dostupnú notifikáciu.
2. Príkazom poll-ack označíte notifikáciu za prijatú a tým sprístupníte novšie až do vyčerpania fronty.

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

• 1000 – notifikácia získaná
• 1003 – vo fronte nie je žiadna neprečítaná notifikácia
• 2150 – váš účet nemá nastavené sťahovanie notifikácií z poll fronty

JSON príkaz poll-req:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizačný reťazec",
    "command": "poll-req",
    "clTRID": "vlastný id kód"
  }
}

JSON odpoveď na poll-req (notifikácia dostupná):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF čas",
    "clTRID": "vlastný id kód",
    "svTRID": "id kód servera",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF čas",
        "clTRID": "vlastný id kód nájdeného príkazu",
        "svTRID": "id kód servera pre nájdený príkaz",
        "command": "názov príkazu",
        "id": "id v POLL fronte"
      }
    }
  }
}

JSON odpoveď na poll-req (prázdna forma notifikácií):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "vlastný id kód",
    "svTRID": "id kód servera",
    "command": "poll-req"
  }
}

Príkazu poll-ack zadávate dáta (parametre):

• id – ID aktuálnej POLL notifikácie

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

• 1002 – označenie notifikácie za prijatú
• 2151 – notifikácia nenájdená

JSON príkaz poll-ack:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizačný reťazec",
    "command": "poll-ack",
    "clTRID": "vlastný id kód",
    "data": {
      "id": “ID prijatej POLL notifikácie”
    }
  }
}

JSON odpoveď na poll-ack:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF čas",
    "clTRID": "vlastný id kód",
    "svTRID": "id kód servera",
    "command": "poll-ack"
  }
}

---

Zoznam návratových kódov

Návratové kódy v odpovediach a notifikáciách Vám pomôžu identifikovať priebeh a prípadné chyby WAPI.

Základné rozdelenie návratových kódov:

• 1xxx – príkaz prebehol v poriadku.
• 2xxx – nesprávny príkaz (napríklad chýbajúce vstupné položky, ich nesprávny formát alebo hodnota).
• 3xxx – chyba cieľového objektu – nemožno vykonať požadovanú akciu, objekt nie je v správnom stave (napríklad pri pokuse o registráciu už obsadenej domény, …).
• 4xxx – chyba pri vykonávaní príkazu (napr. nedostupnosť registra domén, chyba pri komunikácii a pod.).
• 5xxx – interná chyba alebo stav nášho systému.
• x0xx, x1xx – všeobecné.
• x2xx – domény.
• x3xx – DNS.

Konkrétne odpovede vracané na daný príkaz nájdete vždy v dokumentácii príkazu.

---

Slovníček pojmov

• Asynchrónny príkaz: Príkaz vykonávaný dlhší čas, vracia iba hlásenie o prijatí, ďalší priebeh sledujete prostredníctvom notifikácií.
• API: Application Programming Interface. Rozhranie, ktoré Vám umožňuje vlastným kódom získavať dáta alebo spravovať aplikáciu tretej strany.
• Dáta: Obsah niektorých príkazov špecifikujúci detailné nastavenie. Štruktúra dát je daná konkrétnym príkazom.
• JSON: JavaScript Object Notation. Moderný spôsob komunikácie s API.
• Návratový kód: Číslo identifikujúce druh odpovede WAPI na príkaz.
• Notifikácia: JSON alebo XML kód so správami o priebehu asynchrónneho príkazu.
• Príkaz: Požiadavka na WAPI.
• Synchrónny príkaz: Príkaz vykonaný prakticky okamžite. Vracia plnohodnotnú odpoveď, nepoužíva notifikácie.
• Systémové notifikácie: Špeciálny druh notifikácií o udalostiach v systéme, WAPI ich zasiela automaticky v nastavenom formáte.
• UTF-8: Unicode Transformation Format. Rozšírený medzinárodný štandard kódovania znakov podporujúci veľké množstvo písiem.
• WAPI: Rozhranie na správu niektorých častí zákazníckej administrácie (zálohový účet, domény, DNS).
• XML: eXtended Markup Language. Staršia metóda komunikácie s API.

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