WAPI – podręcznik

Z tego artykułu dowiesz się:

• Jak działa WAPI
  • Obsługiwane usługi
  • Ograniczenia zapytań
  • Zapytania synchroniczne i asynchroniczne
  • Kody odpowiedzi
• Jak aktywować WAPI w administracji WEDOS Global
• Jak zintegrować WAPI z Państwa systemem
• Podstawowe zapytania do przetestowania funkcji WAPI
• Rozwiązywanie najczęstszych problemów
• Najczęściej zadawane pytania

---

WEDOS API (WAPI)

WEDOS API, w skrócie WAPI, służy do zarządzania usługami WEDOS bezpośrednio z Państwa systemu za pomocą zapytań i odpowiedzi.

• Komunikacja jest synchroniczna (odpowiedź jest przetwarzana zazwyczaj w ciągu kilku sekund od otrzymania zapytania) lub asynchroniczna (niektóre odpowiedzi mogą trwać dłużej; przebieg jest monitorowany za pomocą notyfikacji).
• Dane są przekazywane protokołem HTTPS metodą POST w parametrze request; kodowanie danych to UTF-8.
• Obsługiwane formaty to zarówno XML i JSON.

Obsługiwane usługi

WAPI obsługuje obecnie następujące usługi WEDOS Global:

• Członkowie WEDOS Global
• WEDOS Protection
• WEDOS DNS i NSSET

Dodatkowo mają Państwo dostęp do usług rejestratora domen WEDOS:

• Domeny
• Kontakty domenowe
• Konto zaliczkowe

Ograniczenia WAPI

W celu ochrony przed nadużyciami WAPI stosuje następujące ograniczenia:

• Jedno konto użytkownika może wysłać maksymalnie 1000 zapytań na godzinę. Dotyczy to wszystkich rodzajów zapytań. Po osiągnięciu tego limitu WAPI odrzuca kolejne zapytania aż do upływu limitu czasu.
• Jedno konto użytkownika może wykonać maksymalnie 100 zapytań o dostępność domeny na godzinę. Dotyczy to zapytań domain-check, domain-create i domain-transfer-check.
• Powtarzające się nieprawidłowe zapytania (nieudana autoryzacja, dostęp z niedozwolonego adresu IP, błędne dane wejściowe, brakujące lub nieprawidłowe parametry, nieznane polecenia, polecenia zakończone dowolnym błędem lub zapytania wykraczające poza pozostałe ograniczenia) powodują zablokowanie adresu IP na 1 minutę za każde nieprawidłowe zapytanie powyżej 10. Przy każdym kolejnym nieprawidłowym zapytaniu system wydłuża czas blokady.

Zapytania synchroniczne i asynchroniczne

Większość zapytań wykonywanych przez WAPI jest synchroniczna – wysyłają Państwo zapytanie i zazwyczaj w ciągu kilku sekund otrzymują wynik.

Niektóre zapytania są asynchroniczne – ich przetwarzanie może trwać bardzo długo (nawet godziny lub dni). W takich przypadkach WAPI nie zwraca wyniku końcowego, lecz jedynie informację o przyjęciu zapytania. System następnie przesyła informacje o postępie i wyniku końcowym w formie notyfikacji.

Kody odpowiedzi

Kody odpowiedzi wskazują stan odpowiedzi WAPI. Część kodów dotyczy konkretnych zapytań i znajduje się w odpowiedniej dokumentacji WAPI; poniższa lista dotyczy wszystkich zapytań.

• 1000 = OK
• 2000 = Błąd przetwarzania zapytania
• 2001 = Nieprawidłowe zapytanie – brakuje wymaganego parametru: user
• 2002 = Nieprawidłowe zapytanie – brakuje wymaganego parametru: auth
• 2003 = Nieprawidłowe zapytanie – brakuje wymaganego parametru: command
• 2004 = Nieprawidłowe zapytanie – dozwolony jest tylko jeden element data
• 2005 = Nieprawidłowe zapytanie – parametr clTRID jest zbyt długi
• 2006 = Przekroczono limit zapytań
• 2007 = Nieprawidłowe zapytanie – przekroczono maksymalny rozmiar zapytania
• 2008 = Nieprawidłowe zapytanie – zapytanie jest zbyt złożone
• 2009 = Nieprawidłowe zapytanie – zapytanie jest puste
• 2010 = Nieznane polecenie
• 2011 = Polecenie wyłączone
• 2050 = Błąd uwierzytelnienia
• 2051 = Dostęp z tego adresu IP jest niedozwolony
• 2052 = Adres IP tymczasowo zablokowany z powodu zbyt wielu błędnych zapytań
• 2100 = Brakuje wymaganego parametru
• 2101 = Niezgodność parametrów
• 2102 = Nieprawidłowe zapytanie – niezgodne kodowanie danych wejściowych
• 4000 = Błąd wewnętrzny
• 4001 = Wyjątek wewnętrzny
• 5000 = Błąd krytyczny
• 5001 = Wewnętrzny błąd uwierzytelnienia
• 5003 = Usługa niedostępna

---

Aktywacja WAPI

Zanim zaczną Państwo korzystać z WAPI, trzeba je aktywować. Należy wykonać następujące kroki:

1. Zaloguj się do administracji WEDOS Global ⧉.
2. Na lewym pasku wybierz WAPI.
3. W formularzu Konfiguracja WAPI wprowadź poniższe dane i zatwierdź przyciskiem Ustaw :
   • Dozwolone adresy IP: Lista adresów IP oddzielonych przecinkami (zarówno IPv4, jak i IPv6, z obsługą notacji CIDR), z których Państwa system łączy się z WAPI.
   • Tryb powiadomień: Sposób odbierania notyfikacji o postępie zapytań asynchronicznych.
   • Preferowany protokół: To ustawienie dotyczy wyłącznie notyfikacji systemowych. Odpowiedzi mają ten sam format co zapytania.
4. W formularzu Ustawienia hasła wprowadź hasło WAPI (dwukrotnie w celu potwierdzenia) i kliknij przycisk Ustaw .

Ustawienia zaczną obowiązywać w ciągu 30 minut.

---

Integracja WAPI z Państwa systemem

Aby zintegrować WAPI ze swoim systemem po jego aktywacji, należy:

• Przygotować skrypt łączący się z API
• Wysłać zapytanie
• Odebrać i przetworzyć odpowiedź
• Odebrać i przetworzyć notyfikację

Połączenie z WAPI

Do połączenia Państwa systemu z WAPI potrzebne są:

• Adres e-mail logowania do WEDOS oraz hasło WAPI
• Adres URL WAPI (zależny od formatu):
  • XML:https://api.wedos.com/wapi/xml
  • JSON:https://api.wedos.com/wapi/json

WAPI korzysta z jednego ciągu uwierzytelniającego, który jest skrótem SHA-1 ciągu złożonego z nazwy użytkownika, skrótu SHA-1 hasła WAPI oraz bieżącej godziny (00-23). Strefa czasowa to Europe/Prague (UTC+1 CET lub UTC+2 CET z uwzględnieniem czasu letniego). Konkretny przykład znajduje się w kodzie poniżej.

Poniższy szablon pokazuje połączenie z WAPI za pomocą skryptu PHP:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'your@login.tld'; 
$wpass = 'your-WAPI-password'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'request name',
  'data' => ['request data'],
  'clTRID' => 'request identifier',
  'test' => '1 (if you only want to test the request)'
  ]
];

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

Zapytanie WAPI

Zapytanie WAPI składa się z następujących danych:

• test: Znacznik trybu testowego, opcjonalny. Jeśli w zapytaniu umieszczą Państwo element test o wartości 1, WAPI tylko sprawdzi polecenie, ale nie wprowadzi żadnych zmian w systemie.
• user: Login (e-mail) Państwa konta klienta WEDOS, wymagany.
• auth: Ciąg autoryzacyjny, wymagany. Jest to skrót SHA-1 ciągu złożonego z nazwy użytkownika, skrótu SHA-1 hasła WAPI oraz bieżącej godziny (00-23). Strefa czasowa to Europe/Prague (UTC+1 CET lub UTC+2 CET z uwzględnieniem czasu letniego). Konkretny przykład znajduje się w kodzie poniżej.
• polecenie: Właściwe zapytanie WAPI. Wymagane.
• clTRID: Identyfikator zapytania, opcjonalny. W tym elemencie można umieścić dowolny ciąg jako identyfikator, który WAPI zwróci w odpowiedzi.
• data: Część danych zapytania. Opcjonalna.

Poniżej znajduje się szablon zapytania JSON:

{
  "request":
  {
    "user": "your@login.tld",
    "auth": "auth-string",
    "command": "request-name",
    "data":
    {
      dane zapytania
    }
    "clTRID": "request-id (optional)",
  }
}

Odpowiedź WAPI

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

• code: Wartość zwracana dla danego zapytania. Więcej informacji o tych kodach znajdą Państwo w rozdziale Kody odpowiedzi oraz w dokumentacji poszczególnych poleceń.
• result: Opis kodu zwrotnego.
• timestamp: Czas wykonania polecenia w formacie UNIX.
• clTRID: Identyfikator zapytania po stronie klienta.
• svTRID: Identyfikator zapytania po stronie serwera.
• polecenie: Zapytanie WAPI.
• data: Dane zwrotne. Brak, jeśli zapytanie się nie powiedzie.
• test: Dołączany do odpowiedzi na zapytania testowe.

Poniżej znajduje się szablon odpowiedzi JSON:

{
  "response": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "request-name"
  }
}

Notyfikacje

Zapytania asynchroniczne nie mogą zostać wykonane natychmiast. Postęp i wynik takich operacji można śledzić za pomocą notyfikacji. Zapytania synchroniczne nie korzystają z notyfikacji.

Jeśli WAPI nie może wykonać operacji natychmiast, zwraca w odpowiedzi Request pending (1001). Po zakończeniu operacji (w przypadku bardziej złożonych działań – poszczególnych kroków) tworzy notyfikację, która przypomina klasyczną odpowiedź. Notyfikację można przypisać do odpowiadającego jej zapytania za pomocą parametrów clTRID lub svTRID.

Dane notyfikacji są zawsze zakodowane w UTF-8.

Notyfikacje można odbierać na następujące sposoby (zgodnie z ustawieniami):

• Za pomocą kolejki POLL.
• Wysyłka na wskazany adres e-mail.
• Za pomocą protokołu HTTP (lub HTTPS) pod wskazany przez Państwa adres URL metodą POST w parametrze request. Za sukces uznawana jest odpowiedź HTTP z kodem zwrotnym 200. Jeśli dostarczenie się nie powiedzie, system będzie ponawiał próby dostarczenia notyfikacji w kilkuminutowych odstępach.

Poniżej znajduje się szablon notyfikacji JSON:

{
  "notify": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "svTRID": "server request id",
    "command": "request-name",
    "ID": "numerical id"
  }
}

---

Podstawowe zapytania

Do podstawowych zapytań należą ping, ping-async, a także 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

Szablon zapytania JSON:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping",
    "clTRID": "user request id"
  }
}

Szablon odpowiedzi JSON:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping"
  }
}

ping-async

Polecenie ping-async testuje działanie notyfikacji WAPI.

Zwracane wartości:

• 1000 – OK
• 1001 – Oczekiwanie na zapytanie

Szablon zapytania JSON:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping-async",
    "clTRID": "user request id"
  }
}

Szablon odpowiedzi JSON:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async"
  }
}

Szablon notyfikacji JSON:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async",
    "id": "poll queue id",
    "data": {
      "round": "attempt number",
      "time": "time",
      "done": 1
    }
  }
}

poll-req i poll-ack

Notyfikacje z kolejki POLL można odbierać, łącząc polecenia poll-req i poll-ack :

1. Użyj poll-req do pobrania najstarszej dostępnej notyfikacji.
2. Poleceniem poll-ack oznaczają Państwo notyfikację jako przeczytaną i udostępniają nowsze, aż do wyczerpania kolejki.

Zwracane wartości dla poll-req to:

• 1000 – notyfikacja odebrana
• 1003 – brak nieprzeczytanej notyfikacji w kolejce
• 2150 – notyfikacje kolejki POLL są dla tego konta wyłączone

JSON poll-req szablon zapytania:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-req",
    "clTRID": "user request id"
  }
}

JSON poll-req szablon odpowiedzi (notyfikacja dostępna):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF time",
        "clTRID": "request user id",
        "svTRID": "request server id",
        "command": "request name",
        "id": "poll queue id"
      }
    }
  }
}

JSON poll-req szablon odpowiedzi (pusta kolejka notyfikacji):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req"
  }
}

Poniższe parametry należy podać w poleceniu poll-ack – zapytanie:

• id – aktualny identyfikator notyfikacji poll

Zwracane wartości dla poll-ack to:

• 1002 – notyfikacja oznaczona jako przeczytana
• 2151 – nie znaleziono notyfikacji

JSON poll-ack – zapytanie:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-ack",
    "clTRID": "user request id",
    "data": {
      "id": “poll notification id”
    }
  }
}

JSON poll-ack odpowiedź:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-ack"
  }
}

---

Rozwiązywanie najczęstszych problemów

Do najczęstszych problemów z WAPI należą:

• Nieudane uwierzytelnienie zapytań

---

FAQ

Czy ten artykuł był pomocny?

Państwa opinia pomaga nam ulepszać artykuły.

TakNie

Czy chcą Państwo przekazać nam coś na temat tego artykułu? (opcjonalnie)

Państwa wiadomość trafi do zespołu redagującego dokumentację, który na nią nie odpowiada. Jeśli potrzebują Państwo pomocy, prosimy skontaktować się z nami za pomocą formularza kontaktowego. Prosimy nie podawać haseł ani danych osobowych.

Pozostaw to pole puste