WAPI – Kézikönyv

Ezen az oldalonWEDOS APIA WAPI aktiválása az ügyfél-adminisztrációbanKommunikáció és hitelesítésAlapparancsokVisszatérési kódok listájaFogalomtár

Ebből a cikkből megtudhatja:


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é:

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:

  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.
Példa a WAPI aktiválására
Példa a WAPI aktiválására

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-list a domain nevében keres, ennél: dns-rows-list a 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-list mindig 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: 

  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"
  }
}

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.

Hasznosnak találta ezt a cikket?

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

Ü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.

Nem találta meg, amit keresett?

Kérdezze meg a többi ügyfelet a Help közösségi weboldalon.