WAPI – Kézikönyv

Ebből a cikkből megtudhatja:

• Hogyan működik a WAPI és mire szolgál
• Hogyan aktiválhatja a WAPI-t az ügyfél-adminisztrációban
• Hogyan zajlik a kommunikáció és a hitelesítés
• Jak stránkovat a hledat v seznamech
• Alapparancsok
• Visszatérési kódok listája
• Fogalomtár

---

WEDOS API

A WEDOS API, vagyis a WAPI, a szolgáltatások közvetlenül az Ön információs rendszeréből történő vezérlésére szolgál. 

A felület használatának feltétele a WEDOS előlegszámlahasználata, amelyről a rendszer levonja a regisztrációk, megújítások, transzferek és egyéb felszámított díjak összegét.

A WAPI jelenleg a következők kezelését teszi lehetővé:

• Előlegszámla ⧉ (account-* és credit-*)
• Domainek ⧉ (domains-* és domain-*)
• Domainkapcsolattartók ⧉ (contact-*)
• NSSET ⧉ (nsset-*)
• DNS ⧉ (dns-*)
• WEDOS Global jogosult felhasználói ⧉ (wg-members-*)
• WEDOS Protection ⧉ (wgp-services-* és wgp-domain-*)

A WAPI korlátozásai

A visszaélések elleni védelem érdekében a WAPI a következő korlátozásokat alkalmazza:

• Egy felhasználói fiókkal óránként legfeljebb 1000 kérést küldhet. Ez minden típusú kérésre vonatkozik; e limit elérésekor a WAPI a időkorlát lejártáig elutasítja a további kéréseket.
• Egy felhasználói fiók óránként legfeljebb 100 domain-elérhetőségi kérést adhat meg. Ez a domain-check, domain-create és domain-transfer-check parancsokra vonatkozik.
• Érvénytelen kérések ismételt küldése (sikertelen hitelesítés, hozzáférés nem engedélyezett IP-címről, hibás bemenet, hiányzó vagy helytelen paraméterek, ismeretlen parancs, hibával végződő parancsok vagy bármely, a többi korlátozáson felüli kérés) 10 érvénytelen kérés túllépése esetén minden további érvénytelen kérésért 1 percre letiltja az IP-címet. Minden újabb hibás kérésnél a rendszer meghosszabbítja a tiltás idejét.

Szinkron és aszinkron műveletek

A WAPI-n keresztül végrehajtott parancsok többsége szinkron – elküldi a parancsot, és általában néhány másodpercen belül megtudja az eredményt. 

Egyes műveletek aszinkronok, vagyis egy ilyen parancs végrehajtása nagyon sokáig is tarthat (akár órákig vagy napokig). A WAPI ezért nem a végeredményt adja vissza, hanem csak a parancs fogadásáról tájékoztat. Az előrehaladásról és a végeredményről a rendszer ezt követően az alábbi formában küld Önnek tájékoztatást: értesítések.

Naplózás

A kérések naplóját az ügyfél-adminisztrációban a következő lépésekkel találja meg:

1. Jelentkezzen be az ügyfél-adminisztrációba ⧉.
2. A felső menüben válassza a My Account Customer.
3. A bal oldali menüben válassza a WAPI requests.

---

A WAPI aktiválása az ügyfél-adminisztrációban

A WAPI használatának megkezdése előtt aktiválja azt az ügyfél-adminisztrációban a következő lépésekkel:

1. Jelentkezzen be az ügyfél-adminisztrációba ⧉.
2. A felső menüben válassza a My Account Customer.
3. A bal oldali menüben válassza a WAPI interface.
4. Állítsa be az engedélyezett IP-címeket (IPv4 vagy IPv6, támogatja a CIDR-t), az értesítések módját, a preferált protokollt és a jelszót.
5. A beállítást a következő gombbal erősítse meg: Set.

---

Kommunikáció és hitelesítés

A WAPI felülettel a kommunikáció HTTPS protokollon keresztül zajlik. Az adatokat POST metódussal, a request paraméterben kell átadni XML vagy JSON formátumban. A parancs és a válasz alapfelépítése minden parancsnál azonos. Az adatok kódolása UTF-8.

A felület URL-címei:

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

A kérés felépítése

A kérés a következő adatokból áll:

• user: Az Ön ügyfélfiókjának felhasználóneve (e-mail-címe), kötelező paraméter.
• auth: Hitelesítő karakterlánc, kötelező paraméter. A felhasználónévből, a WAPI jelszó sha1 hash-éből és az aktuális óra (00-23) értékéből összeállított karakterlánc sha1 hash-e. Az időzóna Europe/Prague (téli idő UTC+1 CET, nyári idő UTC+2 CEST). Konkrét példát lásd az alábbi kódban.
• command: Maga a WAPI parancs. Kötelező paraméter.
• clTRID: A kérés azonosítója, nem kötelező paraméter. Ebbe az elembe tetszőleges karakterláncot beírhat azonosítóként, amelyet a WAPI visszaad a válaszban.
• data: A parancs adatrésze. Nem kötelező paraméter.
• test: Tesztüzemmód jelzője, nem kötelező paraméter. Ha a parancsba beilleszti a test elemet 1 értékkel, a WAPI csak ellenőrzi a parancsot, de nem hajt végre semmilyen módosítást.

A kérés sablonja (JSON) tehát:

{
  "request":
  {
    "user": "az-on@login.tld",
    "auth": "hitelesítő karakterlánc",
    "command": "a kérés neve",
    "data":
    {
      a kérés adatai
    }
    "clTRID": "a kérés azonosítója (nem kötelező)",
    "test": "1 (ha a kérést csak tesztelni szeretné, nem kötelező)"
  }
}

Teljes PHP használati példa (JSON adatformátummal) a következő lehet:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'az-on@login.tld'; 
$wpass = 'az Ön WAPI jelszava'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'a kérés neve',
  'data' => ['a kérés adatainak tömbje'],
  'clTRID' => 'a kérés azonosítója (nem kötelező)',
  'test' => '1 (ha a kérést csak tesztelni szeretné)'
  ]
];

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

A válasz felépítése

A válasz a következő adatokból áll:

• code: A parancs visszatérési értéke. További információkat a következő fejezetben talál: Visszatérési kódok.
• result: A visszatérési kód szöveges leírása.
• timestamp: A parancs végrehajtásának ideje UNIX formátumban.
• clTRID: A parancs azonosítója az ügyfél oldalán.
• svTRID: A parancs azonosítója a szerver oldalán.
• command: A WAPI parancs.
• data: Visszatérési értékek. Ha a parancs sikertelen, adatokat nem ad vissza.
• test: Azokra a parancsokra adott válaszban szerepel, amelyek ezt a jelzőt is tartalmazzák.

Egy példaválasz JSON formátumban például így néz ki:

{
  "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 és 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.

Parancs 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 vagy 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 vagy page_limit vrátí chybu 2101.
• Parancs dns-domains-list vrací total (jako řetězec), page és page_limit vždy. Když page_limit nezadáte nebo zadáte 0, použije 1000.

JSON parancs 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": "az-on@login.tld",
    "auth": "generált hitelesítő karakterlánc",
    "command": "domains-list",
    "clTRID": "saját azonosító kód",
    "data": {
      "status": "active",
      "search": "example",
      "page": 1,
      "page_limit": 2
    }
  }
}

JSON parancs 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": "az-on@login.tld",
    "auth": "generált hitelesítő karakterlánc",
    "command": "dns-rows-list",
    "clTRID": "saját azonosító kód",
    "data": {
      "domain": "example.cz",
      "rdtype": "A",
      "page": 1,
      "page_limit": 50
    }
  }
}

Értesítés

Az aszinkron műveletek nem hajthatók végre azonnal. Az ilyen műveletek előrehaladását és eredményét az értesítéseken keresztül követheti nyomon. A szinkron kérések nem használnak értesítéseket.

Ha a WAPI nem tudja azonnal befejezni a műveletet, a válaszban a következőt adja vissza: Request pending (1001). A művelet befejezése után (összetettebb műveleteknél az egyes lépések után) értesítést hoz létre, amely a klasszikus válasz megfelelője. Az értesítést a clTRID vagy az svTRID paraméter alapján rendelheti hozzá a megfelelő kéréshez.

Az értesítések adatai mindig UTF-8 kódolásúak.

Az értesítéseket a következő módokon kaphatja meg (az aktiváláskor megadott beállítás szerint):

• A POLL soron keresztül.
• A megadott e-mail-címre küldve.
• HTTP (vagy HTTPS) protokollon keresztül, az Ön által megadott URL-címre, POST metódussal, a request paraméterben. Sikeres kézbesítésnek a 200-as válaszkódú HTTP-válasz számít. Ha a kézbesítés nem sikerül, rendszerünk néhány perces időközönként újra megpróbálkozik vele.

Egy példaértesítés JSON formátumban például így néz ki:

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

Rendszerértesítések

A rendszerértesítések fontos eseményekről küldenek információt, jelenleg csak a domain máshová történő transzferéről. Ha a fiókjában aktív a WAPI, a rendszer ezt az információt értesítés formájában küldi el, hasonlóan az aszinkron parancshoz.

Annak a protokollnak a beállítását, amelyben a WAPI a rendszerértesítéseket küldi, a következő fejezet szerint végezze el: A WAPI aktiválása az ügyfél-adminisztrációban. Ez az opció az e-mailre vagy URL-címre küldött értesítéseknél működik. A POLL sorból történő letöltés esetén a válasz a parancséval azonos formátumú.

A felépítés megegyezik a klasszikus értesítésével, a parancs (command) mindig system-notify. A data csomópontban további részletes információkat talál.

---

Alapparancsok

Az alapparancsok közé tartoznak a következők: ping, ping-async és a POLL sorral való munkához szükséges parancsok: poll-req és poll-ack.

ping

A ping parancs a WAPI működésének tesztelésére szolgál – például a bejelentkezési adatok, az IP-cím vagy a kód ellenőrzésére.

A visszatérési értékek:

• 1000 – OK

JSON parancs:

{
  "request": {
    "user": "az-on@login.tld",
    "auth": "generált hitelesítő karakterlánc",
    "command": "ping",
    "clTRID": "saját azonosító kód"
  }
}

JSON válasz:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF idő",
    "clTRID": "saját azonosító kód",
    "svTRID": "a szerver azonosító kódja",
    "command": "ping"
  }
}

ping-async

A ping-async parancs a WAPI-értesítések működését teszteli.

A visszatérési értékek:

• 1000 OK
• 1001 Parancs függőben

JSON parancs:

{
  "request": {
    "user": "az-on@login.tld",
    "auth": "generált hitelesítő karakterlánc",
    "command": "ping",
    "clTRID": "saját azonosító kód"
  }
}

JSON válasz:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF idő",
    "clTRID": "saját azonosító kód",
    "svTRID": "a szerver azonosító kódja",
    "command": "ping"
  }
}

JSON értesítés:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF idő",
    "clTRID": "saját azonosító kód",
    "svTRID": "a szerver azonosító kódja",
    "command": "ping-async",
    "id": "azonosító a POLL sorhoz",
    "data": {
      "round": "a kísérlet száma",
      "time": "idő",
      "done": 1
    }
  }
}

poll-req és poll-ack

Az értesítések POLL sorból történő lekérését a poll-req és poll-ack parancsok kombinációjával végzi: 

1. A poll-req paranccsal letölti a legrégebbi elérhető értesítést.
2. A poll-ack paranccsal az értesítést fogadottnak jelöli, és ezzel hozzáférhetővé teszi az újabbakat a sor kiürüléséig.

A poll-req visszatérési értékei:

• 1000 – értesítés letöltve
• 1003 – a sorban nincs olvasatlan értesítés
• 2150 – a fiókjában nincs beállítva az értesítések letöltése a POLL sorból

JSON parancs poll-req:

{
  "request": {
    "user": "az-on@login.tld",
    "auth": "generált hitelesítő karakterlánc",
    "command": "poll-req",
    "clTRID": "saját azonosító kód"
  }
}

JSON válasz a poll-req parancsra (elérhető értesítés):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF idő",
    "clTRID": "saját azonosító kód",
    "svTRID": "a szerver azonosító kódja",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF idő",
        "clTRID": "a megtalált parancs saját azonosító kódja",
        "svTRID": "a megtalált parancs szerver-azonosító kódja",
        "command": "a parancs neve",
        "id": "azonosító a POLL sorban"
      }
    }
  }
}

JSON válasz a poll-req parancsra (üres értesítési sor):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "saját azonosító kód",
    "svTRID": "a szerver azonosító kódja",
    "command": "poll-req"
  }
}

A poll-ack parancsnak a következő adatokat (paramétereket) adja meg:

• id – az aktuális POLL értesítés azonosítója

A poll-ack visszatérési értékei:

• 1002 – az értesítés fogadottnak jelölve
• 2151 – az értesítés nem található

JSON parancs poll-ack:

{
  "request": {
    "user": "az-on@login.tld",
    "auth": "generált hitelesítő karakterlánc",
    "command": "poll-ack",
    "clTRID": "saját azonosító kód",
    "data": {
      "id": “a fogadott POLL értesítés azonosítója”
    }
  }
}

JSON válasz a poll-ack:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF idő",
    "clTRID": "saját azonosító kód",
    "svTRID": "a szerver azonosító kódja",
    "command": "poll-ack"
  }
}

---

Visszatérési kódok listája

A válaszokban és értesítésekben szereplő visszatérési kódok segítenek azonosítani a WAPI működésének menetét és az esetleges hibákat.

A visszatérési kódok alapvető felosztása:

• 1xxx – a parancs rendben lefutott.
• 2xxx – hibás parancs (például hiányzó bemeneti elemek, azok helytelen formátuma vagy értéke).
• 3xxx – a célobjektum hibája – a kért művelet nem hajtható végre, az objektum nem megfelelő állapotban van (például már foglalt domain regisztrálási kísérletekor stb.).
• 4xxx – hiba a parancs végrehajtása közben (pl. a domainnyilvántartó elérhetetlensége, kommunikációs hiba stb.).
• 5xxx – a rendszerünk belső hibája vagy állapota.
• x0xx, x1xx – általános.
• x2xx – domainek.
• x3xx – DNS.

Az adott parancsra visszaadott konkrét válaszokat mindig a parancs dokumentációjában találja.

---

Fogalomtár

• Aszinkron parancs: Hosszabb ideig végrehajtott parancs, amely csak a fogadásról szóló üzenetet adja vissza; a további folyamatot az értesítéseken keresztül követheti.
• API: Application Programming Interface. Olyan felület, amely lehetővé teszi, hogy saját kóddal adatokat szerezzen vagy harmadik fél alkalmazását kezelje.
• Data: Egyes parancsok tartalma, amely a részletes beállításokat határozza meg. Az adatok szerkezetét az adott parancs határozza meg.
• JSON: JavaScript Object Notation. Az API-val való kommunikáció modern módja.
• Visszatérési kód: A WAPI parancsra adott válaszának típusát azonosító szám.
• Értesítés: JSON vagy XML kód az aszinkron parancs előrehaladásáról szóló üzenetekkel.
• Parancs: Kérés a WAPI felé.
• Szinkron parancs: Gyakorlatilag azonnal végrehajtott parancs. Teljes értékű választ ad vissza, nem használ értesítéseket.
• Rendszerértesítések: Az értesítések speciális fajtája a rendszerben történt eseményekről; a WAPI automatikusan, a beállított formátumban küldi őket.
• UTF-8: Unicode Transformation Format. Elterjedt nemzetközi karakterkódolási szabvány, amely nagyszámú írásrendszert támogat.
• WAPI: Az ügyfél-adminisztráció egyes részeinek (előlegszámla, domainek, DNS) kezelésére szolgáló felület.
• XML: eXtended Markup Language. Az API-val való kommunikáció régebbi módja.

Hasznosnak találta ezt a cikket?

Visszajelzése segít nekünk a cikkek fejlesztésében.

IgenNem

Szeretne üzenni nekünk a cikkel kapcsolatban? (nem kötelező)

Üzenetét a dokumentációs csapat olvassa el, de nem válaszol rá. Ha segítségre van szüksége, forduljon hozzánk a kapcsolatfelvételi űrlapon keresztül. Ne írjon ide jelszavakat vagy személyes adatokat.

Ezt a mezőt hagyja üresen