WAPI - Manuál - VEDOS Znalostní báze

V tomto článku se dozvíte:

Jak WAPI funguje a k čemu slouží
Jak WAPI aktivovat v zákaznické administraci
Jak probíhá komunikace a autentizace
Základní příkazy
Seznam návratových kódů
Slovníček pojmů

WEDOS API

WEDOS API, tedy WAPI, slouží k ovládání služeb přímo z vašeho informačního systému.

Podmínkou pro použití rozhraní je využívání zálohového účtu WEDOS, ze kterého systém odečítá platby za registrace, prodloužení, přeregistrace a další účtované poplatky.

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

Omezení WAPI

Jako ochranu před zneužíváním uplatňuje WAPI tato omezení:

Přes jeden uživatelský účet můžete zaslat max. 1000 požadavků za hodinu. Týká se to všech požadavků všech typů, při dosažení tohoto limitu WAPI další požadavky odmítá až do vypršení časového limitu.
Jeden uživatelský účet smí zadat max. 100 požadavků na dostupnost domény za hodinu. Týká se to příkazů domain-check, domain-create a domain-transfer-check.
Opakované zasílání neplatných požadavků (selhání autorizace, přístup z nepovolené IP adresy, chybný vstup, chybějící nebo nesprávné parametry, neznámý příkaz, příkazy končící jakoukoliv chybou nebo jakýkoliv požadavek nad rámec ostatních omezení) způsobí při překročení 10 neplatných požadavků blokaci IP adresy na 1 minutu za každý neplatný požadavek. S každým dalším chybným požadavkem systém dobu blokování prodlužuje.

Synchronní a asynchronní operace

Většina příkazů prováděných přes WAPI je synchronní – pošlete příkaz a zpravidla během několika sekund se dozvíte výsledek.

Některé operace jsou asychronní, tedy vyřízení takového příkazu může trvat velmi dlouho (i hodiny nebo dny). WAPI tedy nevrátí konečný výsledek, ale pouze informaci o přijetí příkazu. Informace o průběhu a finální výsledek Vám potom systém zasílá formou notifikací.

Aktivace WAPI v zákaznické administraci

Než začnete WAPI používat, aktivujte jej v zákaznické administraci těmito kroky:

Přihlaste se do zákaznické administrace ⧉.
V horním menu vyberte Můj účet Zákazník.
V levém menu vyberte WAPI rozhraní.
Nastavte povolené IP adresy, způsob notifikací, preferovaný protokol a heslo.
Nastavení potvrďte tlačítky Nastavit.

Otevřít nastavení WAPI

Všechna nastavení zadaná při aktivaci můžete později stejným způsobem změnit. Smazáním obsahu pole Povolené IP adresy WAPI deaktivujete.

Komunikace a autentizace

Komunikace s WAPI rozhraním probíhá přes HTTPS protokol. Data jsou předávána metodou POST v parametru request ve formátu XML nebo JSON. Základní tvar příkazu i odpovědi je pro všechny příkazy stejný. Kódování dat je UTF-8.

URL adresy rozhraní:

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

Struktura požadavku

Požadavek sestává z těchto dat:

user: Uživatelské jméno (e-mail) Vašeho zákaznického účtu, povinný parametr.
auth: Autorizační řetězec, povinný parametr. Jedná se o sha1 hash řetězce složeného z uživatelského jména, sha1 hashe WAPI hesla a aktuální hodiny (00-23). Časové pásmo je Europe/Prague (zimní čas UTC+1 SEČ, letní čas UTC+2 SELČ). Konkrétní příklad viz kód níže.
command: Samotný WAPI příkaz. Povinný parametr.
clTRID: ID požadavku, nepovinný parametr. Do tohoto elementu můžete vložit jakýkoliv řetězec jako identifikátor, který WAPI vrátí v odpovědi.
data: Datová část příkazu. Nepovinný parametr.
test: Příznak testovacího režimu, nepovinný parametr. Pokud do příkazu vložíte element test s hodnotou 1, WAPI Váš příkaz pouze zkontroluje, ale nebude provádět žádné změny.

Při komunikaci s WAPI uvádějte heslo k WAPI. Heslo k zákaznickému účtu nefunguje.

Šablona požadavku (JSON) je tedy:

{
  "request":
  {
    "user": "váš@login.tld",
    "auth": "autorizační řetězec",
    "command": "název požadavku",
    "data":
    {
      data požadavku
    }
    "clTRID": "identifikátor požadavku (nepovinné)",
    "test": "1 (pokud chcete požadavek jenom testovat, nepovinné)"
  }
}

Kompletní příklad použití v PHP (datový formát JSON) pak může být:

<?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ázev požadavku',
  'data' => ['pole dat požadavku'],
  'clTRID' => 'identifikátor požadavku (nepovinné)',
  'test' => '1 (pokud chcete požadavek jenom testovat)'
  ]
];

$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=' . $post);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
?>

Struktura odpovědi

Odpověď sestává z těchto dat:

code: Návratová hodnota příkazu. Více informací najdete v kapitole Návratové kódy.
result: Textový popis návratového kódu.
timestamp: Čas vykonání příkazu v UNIXovém formátu.
clTRID: Identifikátor příkazu ze strany klienta.
svTRID: Identifikátor příkazu na straně serveru.
command: WAPI příkaz.
data: Návratové hodnoty. Pokud příkaz selže, data nevrací.
test: Vkládá se při odpovědi na příkazy obsahující také tento příznak.

Vzorová odpověď ve formátu JSON vypadá napří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"
  }
}

Notifikace

Asynchronní operace nelze provést okamžitě. Průběh a výsledek takových operací můžete sledovat prostřednictvím notifikací. Synchronní požadavky notifikace nepoužívají.

Pokud WAPI nedokáže operaci dokončit ihned, v odpovědi vrátí Request pending (1001). Po dokončení operace (u komplikovanějších akcí jednotlivých kroků) vytvoří notifikaci, která je obdobou klasické odpovědi. Notifikaci můžete odpovídajícímu požadavku přiřadit podle parametrů clTRID nebo svTRID.

Data notifikace jsou vždy v kódování UTF-8.

Notifikace můžete získávat těmito způsoby (dle nastavení při aktivaci):

Přes POLL frontu.
Zasláním na uvedenou e-mailovou adresu.
Přes HTTP (či HTTPS) protokol na Vámi stanovenou URL adresu metodou POST v parametru request. Za korektní doručení se považuje HTTP odpověď s návratovým kódem 200. Pokud se doručit nepodaří, bude se náš systém v několikaminutových intervalech pokoušet o doručení znovu.

Vzorová notifikace ve formátu JSON vypadá například takto:

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

Systémové notifikace

Systémové notifikace odesílají informace o relevantních událostech, v současné době pouze o přeregistraci domény jinam. Máte-li u účtu aktivní WAPI, systém takovou informaci odešle prostřednictvím notifikace podobně jako u asynchronního příkazu.

Nastavení protokolu, ve kterém WAPI systémové notifikace odesílá, proveďte podle kapitoly Aktivace WAPI v zákaznické administraci. Tato volba funguje pro notifikace odesílané na e-mail nebo URL adresu. V případě stažení z POLL fronty je odpověď ve stejném tvaru jako příkaz.

Struktura je stejná jako u klasické notifikace, příkaz (command) je vždy system-notify. V uzlu data pak najdete podrobnější informace.

Základní příkazy

Mezi základní příkazy patří ping, ping-async a příkazy pro práci s POLL frontou poll-req a poll-ack.

ping

Příkaz ping slouží k otestování funkčnosti WAPI – například přihlašovacích údajů, IP adresy nebo kódu.

Návratové hodnoty jsou:

1000 – OK

JSON příkaz:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizační řetězec",
    "command": "ping",
    "clTRID": "vlastní id kód"
  }
}

JSON odpověď:

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

ping-async

Příkaz ping-async testuje funkčnost WAPI notifikací.

Návratové hodnoty jsou:

1000 OK
1001 Čekání na příkaz

JSON příkaz:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizační řetězec",
    "command": "ping",
    "clTRID": "vlastní id kód"
  }
}

JSON odpověď:

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

JSON notifikace:

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

poll-req a poll-ack

Získávání notifikací z POLL fronty provádíte kombinací příkazů poll-req a poll-ack:

Příkazem poll-req stáhnete nejstarší dostupnou notifikaci.
Příkazem poll-ack označíte notifikaci za přijatou a tím zpřístupníte novější až do vyčerpání fronty.

Návratové hodnoty pro poll-req jsou:

1000 – notifikace získána
1003 – ve frontě není žádná nepřečtená notifikace
2150 – váš účet nemá nastaveno stahování notifikací z poll fronty

JSON příkaz poll-req:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizační řetězec",
    "command": "poll-req",
    "clTRID": "vlastní id kód"
  }
}

JSON odpověď na poll-req (notifikace dostupná):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF čas",
    "clTRID": "vlastní id kód",
    "svTRID": "id kód serveru",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF čas",
        "clTRID": "vlastní id kód nalezeného příkazu",
        "svTRID": "id kód serveru pro nalezený příkaz",
        "command": "název příkazu",
        "id": "id v POLL frontě"
      }
    }
  }
}

JSON odpověď na poll-req (prázdná forma notifikací):

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

Příkazu poll-ack zadáváte data (parametry):

id – ID aktuální POLL notifikace

Návratové hodnoty pro poll-ack jsou:

1002 – označení notifikace za přijatou
2151 – notifikace nenalezena

JSON příkaz poll-ack:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizační řetězec",
    "command": "poll-ack",
    "clTRID": "vlastní id kód",
    "data": {
      "id": “ID přijaté POLL notifikace”
    }
  }
}

JSON odpověď na poll-ack:

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

Seznam návratových kódů

Návratové kódy v odpovědích a notifikacích Vám pomohou identifikovat průběh a případné chyby WAPI.

Základní rozdělení návratových kódů:

1xxx – příkaz proběhl v pořádku.
2xxx – nesprávný příkaz (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 nebo stav našeho systému.
x0xx, x1xx – obecné.
x2xx – domény.
x3xx – DNS.

Konkrétní odpovědi vracené na daný příkaz najdete vždy v dokumentaci příkazu.

Slovníček pojmů

Asynchronní příkaz: Příkaz vykonávaný delší dobu, vrací jen hlášku o přijetí, další průběh sledujete prostřednictvím notifikací.
API: Application Programming Interface. Rozhraní, které Vám umožňuje vlastním kódem získávat data nebo spravovat aplikaci třetí strany.
Data: Obsah některých příkazů specifikující detailní nastavení. Struktura dat je daná konkrétním příkazem.
JSON: JavaScript Object Notation. Moderní způsob komunikace s API.
Návratový kód: Číslo identifikující druh odpovědi WAPI na příkaz.
Notifikace: JSON nebo XML kód se zprávami o průběhu asynchronního příkazu.
Příkaz: Požadavek na WAPI.
Synchronní příkaz: Příkaz vykonaný prakticky okamžitě. Vrací plnohodnotnou odpověď, nepoužívá notifikace.
Systémové notifikace: Speciální druh notifikací o událostech v systému, WAPI je zasílá automaticky v nastaveném formátu.
UTF-8: Unicode Transformation Format. Rozšířený mezinárodní standard kódování znaků podporující velké množství písem.
WAPI: Rozhraní pro správu některých částí zákaznické administrace (zálohový účet, domény, DNS).
XML: eXtended Markup Language. Starší způsob komunikace s API.

Pomohl Vám návod?

Děkujeme za Vaši zpětnou vazbu!

WAPI – Manuál