WAPI - Priročnik - VEDOS Znalostní báze

V tem članku boste izvedeli:

Kako WAPI deluje in čemu služi
Kako aktivirati WAPI v Customer Administration
Kako poteka komunikacija in avtentikacija
Jak stránkovat a hledat v seznamech
Osnovni ukazi
Seznam povratnih kod
Slovarček pojmov

WEDOS API

WEDOS API, torej WAPI, služi za upravljanje storitev neposredno iz vašega informacijskega sistema.

Pogoj za uporabo vmesnika je uporaba predplačniškega računa WEDOS (Credit Account), s katerega sistem odšteva plačila za registracije, podaljšanja (renewal), prenose (transfer) in druge zaračunane pristojbine.

WAPI trenutno omogoča upravljanje:

Predplačniškega računa (Credit Account) ⧉ (account-* in credit-*)
Domen ⧉ (domains-* in domain-*)
Domenskih kontaktov ⧉ (contact-*)
NSSET-a ⧉ (nsset-*)
DNS ⧉ (dns-*)
Pooblaščenih uporabnikov WEDOS Global ⧉ (wg-members-*)
WEDOS Protection ⧉ (wgp-services-* in wgp-domain-*)

Omejitve WAPI

Kot zaščito pred zlorabo WAPI uporablja naslednje omejitve:

Prek enega uporabniškega računa lahko pošljete največ 1000 zahtevkov na uro. To velja za vse zahtevke vseh vrst; ko je ta omejitev dosežena, WAPI zavrača nadaljnje zahtevke do izteka časovne omejitve.
Posamezen uporabniški račun lahko odda največ 100 zahtevkov za preverjanje razpoložljivosti domene na uro. To velja za ukaze domain-check, domain-create in domain-transfer-check.
Ponavljajoče pošiljanje neveljavnih zahtevkov (neuspešna avtorizacija, dostop z nedovoljenega naslova IP, napačen vnos, manjkajoči ali napačni parametri, neznan ukaz, ukazi, ki se končajo s katero koli napako, ali kateri koli zahtevek, ki presega ostale omejitve) ob preseganju 10 neveljavnih zahtevkov povzroči blokado naslova IP za 1 minuto za vsak neveljaven zahtevek. Z vsakim nadaljnjim napačnim zahtevkom sistem čas blokade podaljšuje.

Sinhrone in asinhrone operacije

Večina ukazov, izvedenih prek WAPI, je sinhronih – ukaz pošljete in rezultat običajno izveste v nekaj sekundah.

Nekatere operacije so asinhrone, zato lahko obdelava takšnega ukaza traja zelo dolgo (tudi ure ali dneve). WAPI torej ne vrne končnega rezultata, ampak le informacijo o sprejemu ukaza. Informacije o poteku in končni rezultat vam nato sistem pošlje v obliki obvestil.

Beleženje

Dnevnik zahtevkov najdete v Customer Administration z naslednjimi koraki:

Prijavite se v Customer Administration ⧉.
V zgornjem meniju izberite My Account Customer.
V levem meniju izberite WAPI requests.

Open WAPI Requests Overview

Aktivacija WAPI v Customer Administration

Preden začnete uporabljati WAPI, ga aktivirajte v Customer Administration z naslednjimi koraki:

Prijavite se v Customer Administration ⧉.
V zgornjem meniju izberite My Account Customer.
V levem meniju izberite WAPI interface.
Nastavite dovoljene naslove IP (IPv4 ali IPv6, podpira CIDR), način obveščanja, prednostni protokol in geslo.
Nastavitve potrdite z gumbom Set.

Open WAPI Settings

Vse nastavitve, vnesene ob aktivaciji, lahko pozneje na enak način spremenite. Z brisanjem vsebine polja Allowed IP addresses WAPI deaktivirate.

Komunikacija in avtentikacija

Komunikacija z vmesnikom WAPI poteka prek protokola HTTPS. Podatki se prenašajo z metodo POST v parametru request v obliki XML ali JSON. Osnovna oblika ukaza in odgovora je za vse ukaze enaka. Kodiranje podatkov je UTF-8.

Naslovi URL vmesnika:

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

Zgradba zahtevka

Zahtevek je sestavljen iz naslednjih podatkov:

user: Uporabniško ime (e-poštni naslov) vašega uporabniškega računa, obvezen parameter.
auth: Avtorizacijski niz, obvezen parameter. Gre za zgoščeno vrednost sha1 niza, sestavljenega iz uporabniškega imena, zgoščene vrednosti sha1 gesla WAPI in trenutne ure (00–23). Časovni pas je Europe/Prague (zimski čas UTC+1 SEČ, poletni čas UTC+2 SELČ). Konkreten primer glejte v kodi spodaj.
command: Sam ukaz WAPI. Obvezen parameter.
clTRID: ID zahtevka, neobvezen parameter. V ta element lahko vstavite poljuben niz kot identifikator, ki ga WAPI vrne v odgovoru.
data: Podatkovni del ukaza. Neobvezen parameter.
test: Zastavica testnega načina, neobvezen parameter. Če v ukaz vstavite element test z vrednostjo 1, WAPI vaš ukaz le preveri, ne izvede pa nobenih sprememb.

Pri komunikaciji z WAPI uporabljajte geslo za WAPI. Geslo za uporabniški račun ne deluje.

Predloga zahtevka (JSON) je torej:

{
  "request":
  {
    "user": "vaš@login.tld",
    "auth": "avtorizacijski niz",
    "command": "ime zahtevka",
    "data":
    {
      podatki zahtevka
    }
    "clTRID": "identifikator zahtevka (neobvezno)",
    "test": "1 (če želite zahtevek samo preizkusiti, neobvezno)"
  }
}

Popoln primer uporabe v PHP (podatkovna oblika JSON) je lahko torej:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'vaš@login.tld'; 
$wpass = 'vaše geslo za WAPI'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'ime zahtevka',
  'data' => ['polje podatkov zahtevka'],
  'clTRID' => 'identifikator zahtevka (neobvezno)',
  'test' => '1 (če želite zahtevek samo preizkusiti)'
  ]
];

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

Zgradba odgovora

Odgovor je sestavljen iz naslednjih podatkov:

code: Povratna vrednost ukaza. Več informacij najdete v poglavju Povratne kode.
result: Besedilni opis povratne kode.
timestamp: Čas izvedbe ukaza v formatu UNIX.
clTRID: Identifikator ukaza na strani odjemalca.
svTRID: Identifikator ukaza na strani strežnika.
command: Ukaz WAPI.
data: Povratne vrednosti. Če ukaz ne uspe, podatkov ne vrne.
test: Vstavi se pri odgovoru na ukaze, ki vsebujejo tudi to zastavico.

Primer odgovora v formatu JSON je videti na primer takole:

{
  "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 in 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.

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

Ukaz JSON 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": "vaš@login.tld",
    "auth": "ustvarjen avtorizacijski niz",
    "command": "domains-list",
    "clTRID": "lastna koda id",
    "data": {
      "status": "active",
      "search": "example",
      "page": 1,
      "page_limit": 2
    }
  }
}

Ukaz JSON 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": "vaš@login.tld",
    "auth": "ustvarjen avtorizacijski niz",
    "command": "dns-rows-list",
    "clTRID": "lastna koda id",
    "data": {
      "domain": "example.cz",
      "rdtype": "A",
      "page": 1,
      "page_limit": 50
    }
  }
}

Obvestilo

Asinhronih operacij ni mogoče izvesti takoj. Potek in rezultat takšnih operacij lahko spremljate prek obvestil. Sinhroni zahtevki obvestil ne uporabljajo.

Če WAPI operacije ne more dokončati takoj, v odgovoru vrne Request pending (1001). Po dokončanju operacije (pri zahtevnejših dejanjih po posameznih korakih) ustvari obvestilo, ki je podobno običajnemu odgovoru. Obvestilo lahko ustreznemu zahtevku prirejate po parametrih clTRID ali svTRID.

Podatki obvestila so vedno v kodiranju UTF-8.

Obvestila lahko prejemate na naslednje načine (glede na nastavitev ob aktivaciji):

Prek čakalne vrste POLL.
S pošiljanjem na navedeni e-poštni naslov.
Prek protokola HTTP (ali HTTPS) na naslov URL, ki ga določite, z metodo POST v parametru request. Za pravilno dostavo se šteje odgovor HTTP s povratno kodo 200. Če dostava ne uspe, bo naš sistem poskušal znova v nekajminutnih intervalih.

Primer obvestila v formatu JSON je videti na primer takole:

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

Sistemska obvestila

Sistemska obvestila pošiljajo informacije o pomembnih dogodkih, trenutno le o prenosu (transfer) domene drugam. Če imate pri računu aktiven WAPI, sistem takšno informacijo pošlje prek obvestila podobno kot pri asinhronem ukazu.

Protokol, v katerem WAPI pošilja sistemska obvestila, nastavite po poglavju Aktivacija WAPI v Customer Administration. Ta možnost deluje za obvestila, poslana na e-pošto ali naslov URL. Pri prevzemu iz čakalne vrste POLL je odgovor v enaki obliki kot ukaz.

Zgradba je enaka kot pri klasičnem obvestilu, ukaz (command) je vedno system-notify. V vozlišču data nato najdete podrobnejše informacije.

Osnovni ukazi

Med osnovne ukaze spadajo ping, ping-async in ukazi za delo s čakalno vrsto POLL poll-req in poll-ack.

ping

Ukaz ping služi za preizkus delovanja WAPI – na primer prijavnih podatkov, naslova IP ali kode.

Povratne vrednosti so:

1000 – OK

Ukaz JSON:

{
  "request": {
    "user": "vaš@login.tld",
    "auth": "ustvarjen avtorizacijski niz",
    "command": "ping",
    "clTRID": "lastna koda id"
  }
}

Odgovor JSON:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "čas UTF",
    "clTRID": "lastna koda id",
    "svTRID": "koda id strežnika",
    "command": "ping"
  }
}

ping-async

Ukaz ping-async preizkuša delovanje obvestil WAPI.

Povratne vrednosti so:

1000 OK
1001 Čakanje na ukaz

Ukaz JSON:

{
  "request": {
    "user": "vaš@login.tld",
    "auth": "ustvarjen avtorizacijski niz",
    "command": "ping",
    "clTRID": "lastna koda id"
  }
}

Odgovor JSON:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "čas UTF",
    "clTRID": "lastna koda id",
    "svTRID": "koda id strežnika",
    "command": "ping"
  }
}

Obvestilo JSON:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "čas UTF",
    "clTRID": "lastna koda id",
    "svTRID": "koda id strežnika",
    "command": "ping-async",
    "id": "id za čakalno vrsto POLL",
    "data": {
      "round": "številka poskusa",
      "time": "čas",
      "done": 1
    }
  }
}

poll-req in poll-ack

Obvestila iz čakalne vrste POLL prevzemate s kombinacijo ukazov poll-req in poll-ack:

Z ukazom poll-req prenesete najstarejše razpoložljivo obvestilo.
Z ukazom poll-ack obvestilo označite kot prejeto in s tem omogočite dostop do novejših, dokler se čakalna vrsta ne izprazni.

Povratne vrednosti za poll-req so:

1000 – obvestilo pridobljeno
1003 – v čakalni vrsti ni nobenega neprebranega obvestila
2150 – vaš račun nima nastavljenega prevzemanja obvestil iz čakalne vrste POLL

Ukaz JSON poll-req:

{
  "request": {
    "user": "vaš@login.tld",
    "auth": "ustvarjen avtorizacijski niz",
    "command": "poll-req",
    "clTRID": "lastna koda id"
  }
}

Odgovor JSON na poll-req (obvestilo je na voljo):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "čas UTF",
    "clTRID": "lastna koda id",
    "svTRID": "koda id strežnika",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "čas UTF",
        "clTRID": "lastna koda id najdenega ukaza",
        "svTRID": "koda id strežnika za najdeni ukaz",
        "command": "ime ukaza",
        "id": "id v čakalni vrsti POLL"
      }
    }
  }
}

Odgovor JSON na poll-req (prazna oblika obvestil):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "lastna koda id",
    "svTRID": "koda id strežnika",
    "command": "poll-req"
  }
}

Ukazu poll-ack podajate podatke (parametre):

id – ID trenutnega obvestila POLL

Povratne vrednosti za poll-ack so:

1002 – obvestilo označeno kot prejeto
2151 – obvestilo ni najdeno

Ukaz JSON poll-ack:

{
  "request": {
    "user": "vaš@login.tld",
    "auth": "ustvarjen avtorizacijski niz",
    "command": "poll-ack",
    "clTRID": "lastna koda id",
    "data": {
      "id": “ID prejetega obvestila POLL”
    }
  }
}

Odgovor JSON na poll-ack:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "čas UTF",
    "clTRID": "lastna koda id",
    "svTRID": "koda id strežnika",
    "command": "poll-ack"
  }
}

Seznam povratnih kod

Povratne kode v odgovorih in obvestilih vam bodo pomagale prepoznati potek in morebitne napake WAPI.

Osnovna razdelitev povratnih kod:

1xxx – ukaz je bil uspešno izveden.
2xxx – napačen ukaz (na primer manjkajoči vnosi, njihova napačna oblika ali vrednost).
3xxx – napaka ciljnega objekta – zahtevanega dejanja ni mogoče izvesti, objekt ni v pravilnem stanju (na primer pri poskusu registracije že zasedene domene, …).
4xxx – napaka pri izvajanju ukaza (npr. nedostopnost registra domen, napaka pri komunikaciji ipd.).
5xxx – notranja napaka ali stanje našega sistema.
x0xx, x1xx – splošno.
x2xx – domene.
x3xx – DNS.

Konkretne odgovore, vrnjene na posamezen ukaz, vedno najdete v dokumentaciji ukaza.

Slovarček pojmov

Asinhroni ukaz: Ukaz, ki se izvaja dlje časa, vrne le sporočilo o sprejemu, nadaljnji potek pa spremljate prek obvestil.
API: Application Programming Interface. Vmesnik, ki vam omogoča, da z lastno kodo pridobivate podatke ali upravljate aplikacijo tretje osebe.
Data: Vsebina nekaterih ukazov, ki določa podrobne nastavitve. Zgradba podatkov je določena s posameznim ukazom.
JSON: JavaScript Object Notation. Sodoben način komunikacije z API.
Povratna koda: Številka, ki določa vrsto odgovora WAPI na ukaz.
Obvestilo: Koda JSON ali XML s sporočili o poteku asinhronega ukaza.
Ukaz: Zahtevek za WAPI.
Sinhroni ukaz: Ukaz, izveden praktično takoj. Vrne polnovreden odgovor, obvestil ne uporablja.
Sistemska obvestila: Posebna vrsta obvestil o dogodkih v sistemu, WAPI jih pošilja samodejno v nastavljenem formatu.
UTF-8: Unicode Transformation Format. Razširjen mednarodni standard kodiranja znakov, ki podpira veliko število pisav.
WAPI: Vmesnik za upravljanje nekaterih delov Customer Administration (predplačniški račun, domene, DNS).
XML: eXtended Markup Language. Starejši način komunikacije z API.

WAPI – Priročnik

WEDOS API

Omejitve WAPI

Sinhrone in asinhrone operacije

Beleženje

Aktivacija WAPI v Customer Administration

Komunikacija in avtentikacija

Zgradba zahtevka

Zgradba odgovora

Stránkování a hledání v seznamech

Obvestilo

Sistemska obvestila

Osnovni ukazi

ping

ping-async

poll-req in poll-ack

Seznam povratnih kod

Slovarček pojmov

Niste našli, kar iščete?

WAPI – Priročnik

WEDOS API

Omejitve WAPI

Sinhrone in asinhrone operacije

Beleženje

Aktivacija WAPI v Customer Administration

Komunikacija in avtentikacija

Zgradba zahtevka

Zgradba odgovora

Stránkování a hledání v seznamech

Obvestilo

Sistemska obvestila

Osnovni ukazi

ping

ping-async

poll-req in poll-ack

Seznam povratnih kod

Slovarček pojmov

Sorodni članki

WMS – Naročilo nove storitve

WebSite 1.0 – Aktivacija HTTPS

WMS – Podatkovne baze

Niste našli, kar iščete?