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
- Hogyan lapozhat és kereshet a listákban
- Alapparancsok
- Visszatérési kódok listája
- Fogalomtár
WEDOS API
A WEDOS API, vagyis a WAPI arra szolgál, hogy a szolgáltatásokat közvetlenül az Ön információs rendszeréből vezérelhesse.
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-*éscredit-*) - Domainek ⧉ (
domains-*ésdomain-*) - Domainkapcsolattartók ⧉ (
contact-*) - NSSET ⧉ (
nsset-*) - DNS ⧉ (
dns-*) - WEDOS Global jogosult felhasználói ⧉ (
wg-members-*) - WEDOS Protection ⧉ (
wgp-services-*éswgp-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 feldolgozása nagyon hosszú ideig 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 küld tájékoztatást. A folyamatról és a végeredményről a rendszer ezt követően értesítést küld Önnek, a következő formában: é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:
- Jelentkezzen be az ügyfél-adminisztrációba ⧉.
- A felső menüben válassza a My Account Customer.
- 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:
- Jelentkezzen be az ügyfél-adminisztrációba ⧉.
- A felső menüben válassza a My Account Customer.
- A bal oldali menüben válassza a WAPI interface.
- Á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.
- A beállítást a következő gombbal erősítse meg: Set.

Az aktiváláskor megadott összes beállítást később ugyanígy módosíthatja. A következő mező tartalmának törlésével: Allowed IP addresses deaktiválhatja a WAPI-t.
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 WAPI-val való kommunikáció során a következőt használja: WAPI jelszó. Az ügyfélfiók jelszava nem működik.
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"
}
}
Lapozás és keresés a listákban
Listázó parancsok domains-list és dns-rows-list opcionális paraméterekkel rendelkeznek a kereséshez és a lapozáshoz. Ha ezeket nem adja meg, a WAPI a korábbiakhoz hasonlóan a teljes listát adja vissza.
Paraméterek a kérés data részében:
- search: A keresett szöveg, kis- és nagybetűk megkülönböztetése nélkül. Ennél:
domains-lista domain nevében keres, ennél:dns-rows-lista rekord nevében vagy adataiban. - page: Az oldal száma 1-től kezdve. Az alapértelmezett érték 1.
- page_limit: Az oldalankénti elemek száma, legfeljebb 1000 (nagyobb értéket a WAPI 1000-re csökkent). Ha nem adja meg, vagy 0-t ad meg, a WAPI az összes elemet visszaadja.
Parancs dns-rows-list parancs további szűrői:
- row_name: A rekord pontos neve. Az érték
@magán a domainen lévő rekordot jelent. - rdtype: A rekord típusa (A, AAAA, MX, TXT…), a kis- és nagybetűk nem számítanak.
Ha ezen paraméterek bármelyikét megadja, a WAPI a listát tömbként adja vissza (a domains-list esetén a domainelemben, a dns-rows-list esetén a rowelemben), és a válasz data részét kiegészíti ezekkel:
- total: A szűrők alkalmazása utáni elemek teljes száma.
- page: A visszaadott oldal száma.
- page_limit: Az alkalmazott oldalankénti elemszám (0 = összes).
Mire figyeljen:
- A lista vége utáni oldal üres listát ad vissza a totalelemmel, nem hibát.
- Az érvénytelen page vagy page_limit értéket (szöveg, negatív szám) a WAPI nem utasítja el, hanem az alapértelmezett értékkel helyettesíti: page 1, page_limit 0, azaz az összes elem.
- Ha a page vagy page_limit értéke tömb, a WAPI 2101-es hibát ad vissza.
- Parancs
dns-domains-listmindig visszaadja a total (karakterláncként), page és page_limit értéket. Ha a page_limit értékét nem adja meg, vagy 0-t ad meg, 1000-et használ.
JSON parancs domains-list (az „example” szöveget tartalmazó aktív domainek, az első oldal két domainnel), részletes leírás a dokumentációban: domains-list parancs ⧉:
{
"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 (az example.cz domain A típusú rekordjai, az első oldal 50 rekorddal), részletes leírás a dokumentációban: dns-rows-list parancs ⧉:
{
"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 próbálkozás 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:
- A poll-req paranccsal letölti a legrégebbi elérhető értesítést.
- 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.
- Adatok: 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.