WAPI - Instrukcja - VEDOS Znalostní báze

W tym artykule dowiesz się:

Jak działa WAPI i do czego służy
Jak aktywować WAPI w administracji klienta
Jak przebiega komunikacja i uwierzytelnianie
Jak stronicować i wyszukiwać na listach
Podstawowe polecenia
Lista kodów zwrotnych
Słowniczek pojęć

WEDOS API

WEDOS API, czyli WAPI, służy do zarządzania usługami bezpośrednio z Twojego systemu informatycznego.

Warunkiem korzystania z interfejsu jest wykorzystywanie konta kredytowego WEDOS, z którego system pobiera opłaty za rejestracje, odnowienia, transfery i inne naliczane opłaty.

WAPI obecnie umożliwia zarządzanie:

Kontem kredytowym ⧉ (account-* i credit-*)
Domenami ⧉ (domains-* i domain-*)
Kontaktami domen ⧉ (contact-*)
NSSET ⧉ (nsset-*)
DNS ⧉ (dns-*)
Uprawnionymi użytkownikami WEDOS Global ⧉ (wg-members-*)
WEDOS Protection ⧉ (wgp-services-* i wgp-domain-*)

Ograniczenia WAPI

Jako ochronę przed nadużyciami WAPI stosuje następujące ograniczenia:

Za pośrednictwem jednego konta użytkownika można wysłać maksymalnie 1000 żądań na godzinę. Dotyczy to wszystkich żądań wszystkich typów. Po osiągnięciu tego limitu WAPI odrzuca kolejne żądania do czasu upłynięcia limitu czasowego.
Jedno konto użytkownika może wysłać maksymalnie 100 żądań sprawdzenia dostępności domeny na godzinę. Dotyczy to poleceń domain-check, domain-create i domain-transfer-check.
Wielokrotne wysyłanie nieprawidłowych żądań (niepowodzenie autoryzacji, dostęp z niedozwolonego adresu IP, błędne dane wejściowe, brakujące lub nieprawidłowe parametry, nieznane polecenie, polecenia kończące się dowolnym błędem lub jakiekolwiek żądanie wykraczające poza pozostałe ograniczenia) po przekroczeniu 10 nieprawidłowych żądań powoduje zablokowanie adresu IP na 1 minutę za każde nieprawidłowe żądanie. Z każdym kolejnym błędnym żądaniem system wydłuża czas blokady.

Operacje synchroniczne i asynchroniczne

Większość poleceń wykonywanych przez WAPI jest synchroniczna – wysyłasz polecenie i zazwyczaj w ciągu kilku sekund poznajesz wynik.

Niektóre operacje są asynchroniczne, co oznacza, że realizacja takiego polecenia może trwać bardzo długo (nawet godziny lub dni). WAPI nie zwraca wtedy wyniku końcowego, a jedynie informację o przyjęciu polecenia. Informacje o przebiegu i wynik końcowy system wysyła następnie w formie powiadomień.

Rejestrowanie zdarzeń

Log żądań znajdziesz w administracji klienta, wykonując następujące kroki:

Zaloguj się do administracji klienta ⧉.
W górnym menu wybierz My Account Customer.
W lewym menu wybierz WAPI requests.

Otwórz przegląd żądań WAPI

Aktywacja WAPI w administracji klienta

Zanim zaczniesz korzystać z WAPI, aktywuj je w administracji klienta, wykonując następujące kroki:

Zaloguj się do administracji klienta ⧉.
W górnym menu wybierz My Account Customer.
W lewym menu wybierz WAPI interface.
Ustaw dozwolone adresy IP (IPv4 lub IPv6, obsługiwany jest CIDR), sposób powiadomień, preferowany protokół i hasło.
Ustawienia potwierdź przyciskami Set.

Otwórz ustawienia WAPI

Wszystkie ustawienia wprowadzone podczas aktywacji możesz później zmienić w ten sam sposób. Usunięcie zawartości pola Allowed IP addresses dezaktywuje WAPI.

Komunikacja i uwierzytelnianie

Komunikacja z interfejsem WAPI odbywa się przez protokół HTTPS. Dane są przekazywane metodą POST w parametrze request w formacie XML lub JSON. Podstawowa postać polecenia i odpowiedzi jest taka sama dla wszystkich poleceń. Kodowanie danych to UTF-8.

Adresy URL interfejsu:

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

Struktura żądania

Żądanie składa się z następujących danych:

user: Nazwa użytkownika (e-mail) Twojego konta klienta, parametr wymagany.
auth: Ciąg autoryzacyjny, parametr wymagany. Jest to skrót sha1 ciągu złożonego z nazwy użytkownika, skrótu sha1 hasła WAPI i aktualnej godziny (00-23). Strefa czasowa to Europe/Prague (czas zimowy UTC+1 CET, czas letni UTC+2 CEST). Konkretny przykład znajdziesz w kodzie poniżej.
command: Samo polecenie WAPI. Parametr wymagany.
clTRID: Identyfikator żądania, parametr opcjonalny. W tym elemencie możesz umieścić dowolny ciąg znaków jako identyfikator, który WAPI zwróci w odpowiedzi.
data: Część danych polecenia. Parametr opcjonalny.
test: Znacznik trybu testowego, parametr opcjonalny. Jeśli do polecenia dodasz element test o wartości 1, WAPI jedynie sprawdzi Twoje polecenie, ale nie wprowadzi żadnych zmian.

Podczas komunikacji z WAPI podawaj hasło do WAPI. Hasło do konta klienta nie działa.

Szablon żądania (JSON) wygląda więc tak:

{
  "request":
  {
    "user": "twoj@login.tld",
    "auth": "ciąg autoryzacyjny",
    "command": "nazwa żądania",
    "data":
    {
      dane żądania
    }
    "clTRID": "identyfikator żądania (opcjonalnie)",
    "test": "1 (jeśli chcesz tylko przetestować żądanie, opcjonalnie)"
  }
}

Kompletny przykład użycia w PHP (format danych JSON) może wyglądać tak:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'twoj@login.tld'; 
$wpass = 'twoje hasło do WAPI'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'nazwa żądania',
  'data' => ['tablica danych żądania'],
  'clTRID' => 'identyfikator żądania (opcjonalnie)',
  'test' => '1 (jeśli chcesz tylko przetestować żądanie)'
  ]
];

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

Struktura odpowiedzi

Odpowiedź składa się z następujących danych:

code: Wartość zwracana przez polecenie. Więcej informacji znajdziesz w rozdziale Kody zwrotne.
result: Tekstowy opis kodu zwrotnego.
timestamp: Czas wykonania polecenia w formacie UNIX.
clTRID: Identyfikator polecenia po stronie klienta.
svTRID: Identyfikator polecenia po stronie serwera.
command: Polecenie WAPI.
data: Wartości zwracane. Jeśli polecenie zakończy się niepowodzeniem, dane nie są zwracane.
test: Dodawany w odpowiedzi na polecenia zawierające również ten znacznik.

Przykładowa odpowiedź w formacie JSON wygląda na przykład tak:

{
  "response":
  {
    "code": "1000",
    "result": "ok",
    "timestamp": "1286356644",
    "svTRID": "1286356644.0246.21616",
    "command": "domain-create",
    "data": 		
    {
      "num": "1311000863",
      "expiration": "2011-10-06"
    },
    "test": "1"
  }
}

Stronicowanie i wyszukiwanie na listach

Polecenia zwracające listy domains-list i dns-rows-list mają opcjonalne parametry służące do wyszukiwania i stronicowania. Jeśli nie zostaną podane, WAPI zwróci odpowiedź tak jak dotychczas, czyli całą listę.

Parametry w części data żądania:

search: Szukany tekst, bez rozróżniania wielkości liter. W przypadku domains-list wyszukiwanie obejmuje nazwę domeny, w przypadku dns-rows-list – nazwę lub dane rekordu.
page: Numer strony, liczony od 1. Wartość domyślna to 1.
page_limit: Liczba pozycji na stronę, maksymalnie 1000 (wyższą wartość WAPI obniży do 1000). Jeśli parametr nie zostanie podany lub zostanie podane 0, WAPI zwróci wszystkie pozycje.

Polecenie dns-rows-list ma dodatkowo następujące filtry:

row_name: Dokładna nazwa rekordu. Wartość @ oznacza rekord bezpośrednio na domenie.
rdtype: Typ rekordu (A, AAAA, MX, TXT…), wielkość liter nie ma znaczenia.

Jeśli zostanie podany którykolwiek z tych parametrów, WAPI zwróci listę jako tablicę (w przypadku domains-list w elemencie domain, w przypadku dns-rows-list w elemencie row) i w części data odpowiedzi doda:

total: Łączna liczba pozycji po zastosowaniu filtrów.
page: Numer zwróconej strony.
page_limit: Zastosowana liczba pozycji na stronę (0 oznacza wszystkie).

Na co zwrócić uwagę:

Strona za końcem listy zwróci pustą listę z elementem total, a nie błąd.
Nieprawidłowej wartości page lub page_limit (tekst, liczba ujemna) WAPI nie odrzuci, lecz zastąpi ją wartością domyślną: page 1, page_limit 0, czyli wszystkie pozycje.
Tablica zamiast wartości w page lub page_limit zwróci błąd 2101.
Polecenie dns-domains-list zwraca total (jako ciąg znaków), page i page_limit zawsze. Jeśli page_limit nie zostanie podany lub zostanie podane 0, użyta zostanie wartość 1000.

Polecenie JSON domains-list (aktywne domeny zawierające „example”, pierwsza strona po dwie domeny), szczegółowy opis w dokumentacji polecenia domains-list ⧉:

{
  "request": {
    "user": "twoj@login.tld",
    "auth": "wygenerowany ciąg autoryzacyjny",
    "command": "domains-list",
    "clTRID": "własny kod id",
    "data": {
      "status": "active",
      "search": "example",
      "page": 1,
      "page_limit": 2
    }
  }
}

Polecenie JSON dns-rows-list (rekordy typu A domeny example.cz, pierwsza strona po 50 rekordów), szczegółowy opis w dokumentacji polecenia dns-rows-list ⧉:

{
  "request": {
    "user": "twoj@login.tld",
    "auth": "wygenerowany ciąg autoryzacyjny",
    "command": "dns-rows-list",
    "clTRID": "własny kod id",
    "data": {
      "domain": "example.cz",
      "rdtype": "A",
      "page": 1,
      "page_limit": 50
    }
  }
}

Powiadomienie

Operacji asynchronicznych nie można wykonać natychmiast. Przebieg i wynik takich operacji możesz śledzić za pomocą powiadomień. Żądania synchroniczne nie korzystają z powiadomień.

Jeśli WAPI nie może zakończyć operacji od razu, w odpowiedzi zwróci Request pending (1001). Po zakończeniu operacji (przy bardziej złożonych działaniach – poszczególnych kroków) utworzy powiadomienie, które jest odpowiednikiem klasycznej odpowiedzi. Powiadomienie możesz przypisać do odpowiedniego żądania na podstawie parametrów clTRID lub svTRID.

Dane powiadomienia są zawsze kodowane w UTF-8.

Powiadomienia możesz otrzymywać w następujący sposób (zależnie od ustawień wybranych podczas aktywacji):

Przez kolejkę POLL.
Wysyłką na podany adres e-mail.
Przez protokół HTTP (lub HTTPS) na wskazany przez Ciebie adres URL metodą POST w parametrze request. Za prawidłowe dostarczenie uznawana jest odpowiedź HTTP z kodem zwrotnym 200. Jeśli dostarczenie się nie powiedzie, nasz system będzie ponawiał próby dostarczenia w odstępach kilku minut.

Przykładowe powiadomienie w formacie JSON wygląda na przykład tak:

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

Powiadomienia systemowe

Powiadomienia systemowe przesyłają informacje o istotnych zdarzeniach, obecnie tylko o transferze domeny gdzie indziej. Jeśli masz na koncie aktywne WAPI, system wyśle taką informację w powiadomieniu, podobnie jak w przypadku polecenia asynchronicznego.

Ustawienia protokołu, w którym WAPI wysyła powiadomienia systemowe, wprowadź zgodnie z rozdziałem Aktywacja WAPI w administracji klienta. Ta opcja działa dla powiadomień wysyłanych na adres e-mail lub URL. W przypadku pobierania z kolejki POLL odpowiedź ma taką samą postać jak polecenie.

Struktura jest taka sama jak w przypadku klasycznego powiadomienia, polecenie (command) to zawsze system-notify. W węźle data znajdziesz bardziej szczegółowe informacje.

Podstawowe polecenia

Do podstawowych poleceń należą ping, ping-async oraz polecenia do pracy z kolejką POLL poll-req i poll-ack.

ping

Polecenie ping służy do testowania działania WAPI – na przykład danych logowania, adresu IP lub kodu.

Zwracane wartości:

1000 – OK

Polecenie JSON:

{
  "request": {
    "user": "twoj@login.tld",
    "auth": "wygenerowany ciąg autoryzacyjny",
    "command": "ping",
    "clTRID": "własny kod id"
  }
}

Odpowiedź JSON:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "czas UTF",
    "clTRID": "własny kod id",
    "svTRID": "kod id serwera",
    "command": "ping"
  }
}

ping-async

Polecenie ping-async testuje działanie powiadomień WAPI.

Zwracane wartości:

1000 OK
1001 Oczekiwanie na polecenie

Polecenie JSON:

{
  "request": {
    "user": "twoj@login.tld",
    "auth": "wygenerowany ciąg autoryzacyjny",
    "command": "ping",
    "clTRID": "własny kod id"
  }
}

Odpowiedź JSON:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "czas UTF",
    "clTRID": "własny kod id",
    "svTRID": "kod id serwera",
    "command": "ping"
  }
}

Powiadomienie JSON:

{
  "notify": {
    "code": "1000",
    "result": "OK",
    "timestamp": "czas UTC",
    "clTRID": "własny kod id",
    "svTRID": "kod id serwera",
    "command": "ping-async",
    "id": "id dla kolejki POLL",
    "data": {
      "round": "numer próby",
      "time": "czas",
      "done": 1
    }
  }
}

poll-req i poll-ack

Powiadomienia z kolejki POLL pobierasz, łącząc polecenia poll-req i poll-ack:

Poleceniem poll-req pobierasz najstarsze dostępne powiadomienie.
Poleceniem poll-ack oznaczasz powiadomienie jako odebrane, co udostępnia nowsze, aż do wyczerpania kolejki.

Zwracane wartości dla poll-req:

1000 – powiadomienie pobrane
1003 – w kolejce nie ma żadnego nieprzeczytanego powiadomienia
2150 – Twoje konto nie ma skonfigurowanego pobierania powiadomień z kolejki poll

Polecenie JSON poll-req:

{
  "request": {
    "user": "twoj@login.tld",
    "auth": "wygenerowany ciąg autoryzacyjny",
    "command": "poll-req",
    "clTRID": "własny kod id"
  }
}

Odpowiedź JSON na poll-req (powiadomienie dostępne):

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "czas UTF",
    "clTRID": "własny kod id",
    "svTRID": "kod id serwera",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": "1000",
        "result": "OK",
        "timestamp": "czas UTF",
        "clTRID": "własny kod id znalezionego polecenia",
        "svTRID": "kod id serwera dla znalezionego polecenia",
        "command": "nazwa polecenia",
        "id": "id w kolejce POLL"
      }
    }
  }
}

Odpowiedź JSON na poll-req (pusta kolejka powiadomień):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": "1286962852",
    "clTRID": "własny kod id",
    "svTRID": "kod id serwera",
    "command": "poll-req"
  }
}

W poleceniu poll-ack podajesz dane (parametry):

id – ID bieżącego powiadomienia POLL

Zwracane wartości dla poll-ack:

1002 – powiadomienie oznaczone jako odebrane
2151 – nie znaleziono powiadomienia

Polecenie JSON poll-ack:

{
  "request": {
    "user": "twoj@login.tld",
    "auth": "wygenerowany ciąg autoryzacyjny",
    "command": "poll-ack",
    "clTRID": "własny kod id",
    "data": {
      "id": "ID otrzymanego powiadomienia POLL"
    }
  }
}

Odpowiedź JSON na poll-ack:

{
  "response": {
    "code": "1002",
    "result": "Notification acquired",
    "timestamp": "czas UTC",
    "clTRID": "własny kod id",
    "svTRID": "kod id serwera",
    "command": "poll-ack"
  }
}

Lista kodów zwrotnych

Kody zwrotne w odpowiedziach i powiadomieniach pomogą Ci zidentyfikować przebieg i ewentualne błędy WAPI.

Podstawowy podział kodów zwrotnych:

1xxx – polecenie wykonane prawidłowo.
2xxx – nieprawidłowe polecenie (na przykład brakujące pola wejściowe, ich nieprawidłowy format lub wartość).
3xxx – błąd obiektu docelowego – nie można wykonać żądanej akcji, obiekt nie jest w prawidłowym stanie (na przykład przy próbie rejestracji już zajętej domeny, …).
4xxx – błąd podczas wykonywania polecenia (np. niedostępność rejestru domen, błąd komunikacji itp.).
5xxx – błąd wewnętrzny lub stan naszego systemu.
x0xx, x1xx – ogólne.
x2xx – domeny.
x3xx – DNS.

Konkretne odpowiedzi zwracane dla danego polecenia znajdziesz zawsze w dokumentacji polecenia.

Słowniczek pojęć

Polecenie asynchroniczne: Polecenie wykonywane dłuższy czas, zwraca tylko komunikat o przyjęciu, dalszy przebieg śledzisz za pomocą powiadomień.
API: Application Programming Interface. Interfejs, który umożliwia za pomocą własnego kodu pobieranie danych lub zarządzanie aplikacją strony trzeciej.
Dane: Zawartość niektórych poleceń określająca szczegółowe ustawienia. Struktura danych zależy od konkretnego polecenia.
JSON: JavaScript Object Notation. Nowoczesny sposób komunikacji z API.
Kod zwrotny: Liczba określająca rodzaj odpowiedzi WAPI na polecenie.
Powiadomienie: Kod JSON lub XML z komunikatami o przebiegu polecenia asynchronicznego.
Polecenie: Żądanie do WAPI.
Polecenie synchroniczne: Polecenie wykonywane praktycznie natychmiast. Zwraca pełną odpowiedź, nie korzysta z powiadomień.
Powiadomienia systemowe: Specjalny rodzaj powiadomień o zdarzeniach w systemie, WAPI wysyła je automatycznie w ustawionym formacie.
UTF-8: Unicode Transformation Format. Rozpowszechniony międzynarodowy standard kodowania znaków obsługujący dużą liczbę pism.
WAPI: Interfejs do zarządzania niektórymi częściami administracji klienta (konto kredytowe, domeny, DNS).
XML: eXtended Markup Language. Starszy sposób komunikacji z API.

WAPI – Instrukcja

WEDOS API

Ograniczenia WAPI

Operacje synchroniczne i asynchroniczne

Rejestrowanie zdarzeń

Aktywacja WAPI w administracji klienta

Komunikacja i uwierzytelnianie

Struktura żądania

Struktura odpowiedzi

Stronicowanie i wyszukiwanie na listach

Powiadomienie

Powiadomienia systemowe

Podstawowe polecenia

ping

ping-async

poll-req i poll-ack

Lista kodów zwrotnych

Słowniczek pojęć

Nie znalazłeś tego, czego szukasz?

WAPI – Instrukcja

WEDOS API

Ograniczenia WAPI

Operacje synchroniczne i asynchroniczne

Rejestrowanie zdarzeń

Aktywacja WAPI w administracji klienta

Komunikacja i uwierzytelnianie

Struktura żądania

Struktura odpowiedzi

Stronicowanie i wyszukiwanie na listach

Powiadomienie

Powiadomienia systemowe

Podstawowe polecenia

ping

ping-async

poll-req i poll-ack

Lista kodów zwrotnych

Słowniczek pojęć

Powiązane poradniki

WMS – Zamówienie nowej usługi

WebSite 1.0 – Aktywacja HTTPS

WMS – Bazy danych

Nie znalazłeś tego, czego szukasz?