WAPI – základy komunikace, autentizace

Komunikace s WAPI rozhraním probíhá přes HTTPS prokotol. Data jsou předávána metodou POSTv parametru request. Data jsou ve formátu XML. Základní tvar dotazu i odpovědi je pro všechny příkazy stejný. Dotazy jsou zpracovávány v kódování UTF-8.

URL adresy rozhraní:

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

Dotaz

<request>
 <user>tester</user>
 <auth>202b62bc4646281f97d225db1249840c8452dd8f</auth>
 <command>domain-create</command>
 <clTRID>a44B</clTRID>
 <data>
  <name>example.cz</name>
  <period>1</period>
  <dns></dns>
  <owner_c>CONTACT</owner_c>
  <admin_c>CONTACT</admin_c>
 </data>
 <test>1</test>
</request>

user

Uživatelské jméno Vašeho zákaznického účtu, povinný parametr.

auth

Autorizační řetězec, sloužící k autorizaci dotazu, povinný parametr.

Jedná se o sha1 hash řetězce složeného z Vašeho uživatelského jména, sha1 hashe WAPI hesla účtu a aktuální hodiny (00-23). Časové pásmo je Europe/Prague (zimní čas UTC+1 SEČ, letní čas UTC+2 SELČ). Autorizační řetězec uživatele tester, s WAPI heslem 123456, odeslaný v 11:30 bude před konečným hashováním vypadat takto:

tester7c4a8d09ca3762af61e59520943dc26494f8941b11

a po použití funkce sha1 takto:

ac28237e80e68efa3bfd07f42dca3d41c5986e01

Takto například vypadá vytváření autorizačního řetězce v jazyce PHP:

$auth = sha1($login.sha1($wpass).date('H', time()));

Hodinu je třeba zadávat vždy dvěma ciframi.

command

WAPI příkaz. Povinný partametr.

clTRID

ID požadavku, nepovinný parametr.

Do tohoto elementu můžete vložit jakýkoliv řetězec. Pokud tak učiníte, bude tento identifikátor vrácen v odpovědi. Slouží k vaší identifikaci jednotlivých požadavků, hlavně u asynchronních příkazů (vykonávají se se zpožděním), kde odpověď není vrácena hned a při velkém množství operací by jinak bylo nemožné rozlišit, která odpověď patří ke kterému dotazu.

data

Datová část dotazu. Nepovinný parametr.

Pokud příkaz vyžaduje předání nějakých informací (u domén například nejčastěji název domény), vkládají se do tohoto elementu. U každého příkazu je přesně popsáno, jaká data v jakém formátu je potřeba předat.

test

Příznak testovacího režimu, nepovinný parametr.

Pokud do dotazu vložíte element test s hodnotou 1, systém Váš dotaz pouze zkontroluje, ale nebude provádět žádné změny. Tento příznak je určen pro testování Vašich systémů před ostrým nasazením.

Odpověď

Na každý dotaz WAPI vrací vždy odpověď ve formátu XML, která obsahuje alespoň elementy coderesult. V poli code je vrácen návratový kód odpovědi, v result pak jeho textový popis. Návratové kódy jsou pro přehlednost rozděleny do kategorií:

  • 1xxx – příkaz proběhl v pořádku.
  • 2xxx – nesprávný dotaz (například chybějící vstupní položky, jejich nesprávný formát či hodnota).
  • 3xxx – chyba cílového objektu – nelze provést požadovanou akci, objekt není ve správném stavu (například při pokusu o registraci již obsazené domény, …).
  • 4xxx – chyba při provádění příkazu (např. nedostupnost registru domén, chyba při komunikaci aj.)
  • 5xxx – interní chyba v našem systému

Odpověď 1: OK [1XXX]

<response>
 <code>1000</code>
 <result>OK</result>
 <timestamp>1286356644</timestamp>
 <clTRID>a44B</clTRID>
 <svTRID>1286356644.0246.21616</svTRID>
 <command>domain-create</command>
 <data>
   <num>1311000863</num>
   <expiration>2011-10-06</expiration>
 </data>
 <test>1</test>
</response>

Takto vypadá odpověď, kdy je vše v pořádku a akce byla úspěšně vykonána.

WAPI vždy vrací odpověď ve formátu XML, obsahující položky coderesulttimestampsvTRID command. Může se ale stát, že není možné některé z těchto položek do odpovědi vložit (například při špatném formátu dotazu). Elementy code a result jsou v odpovědi za jakýchkoliv okolností.

Pokud byly v dotazu parametry clTRID, nebo test, jsou obsaženy i v odpovědi. Element data je vkládán pouze v případě, že je třeba vrátit nějaká data.

code

Element code obsahuje návratovou hodnotu příkazu. Systém návratových kódů a jejich seznam je na stránce WAPI – seznam návratových kódů.

result

Textový popis návratového kódu.

timestamp

Čas vykonání příkazu v UNIXovém formátu.

clTRID

Identifikátor dotazu ze strany klienta.

svTRID

Identifikátor dotazu na straně serveru.

command

WAPI Příkaz.

data

V případě, že příkaz vrací nějaké hodnoty, jsou uloženy v tomto elementu. Přesný popis návratových hodnot je popsán u každého příkazu.

Pokud příkaz selže (tj. jiný návratový kód než 1000), parametr data se nevkládá.

test

Příznak testovacího režimu. 

Vkládá se při odpovědi na dotazy obsahující také tento příznak.

Odpověď 2: Chyba [XXXX]

<response>
 <code>4050</code>
 <result>Command not exists</result>
 <timestamp>1286543689</timestamp>
 <clTRID>E8bQ</clTRID>
 <svTRID>1286543689.2416.28124</svTRID>
 <command>omain-transfer-check</command>
</response>

Takto vypadá chybová odpověď, v tomto případě se jedná o neznámý příkaz.

Děkujeme za zpětnou vazbu!