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 codea result. 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 code, result, timestamp, svTRID a 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.