REST API – Usługi WEDOS.protection

WEDOS REST API jest wciąż w fazie rozwoju. Dostęp i funkcje mogą ulec zmianie bez wcześniejszego powiadomienia.

Ten artykuł częściowo opisuje endpoint WEDOS.protection w WEDOS REST API. Domeny WEDOS.protection i członkowie mają własne artykuły. Informacje o WEDOS API (WAPI) zawiera artykuł WAPI – WEDOS Protection.

Podstawowe informacje o WEDOS REST API zawiera artykuł Podręcznik WEDOS REST API.

W tym artykule znajdują się następujące informacje:

Dostęp do endpointu WGP

WGP HTTP REST API v2 służy do zarządzania domenami, usługami i zaproszeniami do współzarządzania w WEDOS.protection (WGP).

Podstawowy adres URL i uwierzytelnianie

Podstawowy adres URL endpointów WGP to: https://api.wedos.com/v2

Uwierzytelnianie odbywa się wyłącznie przez OAuth2: w nagłówku żądania należy podać ważny token dostępu (Authorization: Bearer <TOKEN>) ze scope wgp . Bez ważnego tokenu API zwraca błąd 2000.

Można dodać parametr example=1 do dowolnego endpointu jako parametr GET (?example=1 dla endpointów bez własnych parametrów GET, w przeciwnym razie &example=1). API zwróci wtedy przykładowe polecenie curl dla tego wywołania, bez konieczności podawania prawdziwych parametrów. Również w tym trybie wymagane jest prawidłowe uwierzytelnienie.

Przegląd endpointów

MetodaEndpointOpis
GET/servicesLista samodzielnych usług WGP
POST/services/{service_id}/cache/purgeWyczyszczenie pamięci podręcznej CDN
POST/services/{service_id}/renewPrzedłużenie usługi
POST/services/{service_id}/template-replicateReplikacja ustawień z domeny szablonowej
PATCH/services/{service_id}Zmiana wariantu/okresu abonamentowego usługi
DELETE/services/{service_id}Usunięcie/zakończenie usługi

Format odpowiedzi

Odpowiedź API jest zawsze obiektem JSON z kluczami code (kod zwrotny), msg (opis tekstowy), request_id (identyfikator żądania) oraz, jeśli dotyczy, data (dane zwracane przy powodzeniu).

Ogólne kody zwrotne obowiązujące dla wszystkich endpointów (warstwa REST, niezależnie od konkretnej operacji):

  • 1000 – powodzenie (OK)
  • 2000 – brak lub nieprawidłowe uwierzytelnienie (token OAuth2 Bearer)
  • 2004 – przekroczono maksymalny rozmiar żądania (URL lub treść żądania)
  • 4000 – nieznana/nieobsługiwana metoda API (wywołana kombinacja metody HTTP i ścieżki nie istnieje)
  • 4001 – walidacja danych wejściowych nie powiodła się
  • 4005 – dla bieżącego endpointu w trybie example=1 nie jest dostępny żaden przykład
  • 6000 – błąd wewnętrzny podczas inicjalizacji bazowego polecenia WAPI

Dodatkowo każdy endpoint zwraca własne kody biznesowe specyficzne dla danej operacji (odpowiadające bazowemu poleceniu WAPI). Są one wymienione w sekcji Kody zwrotne przy każdym endpoincie.

GET /services

Zwraca listę własnych samodzielnych usług WEDOS Global Protection zalogowanego użytkownika OAuth2 (utworzonych bezpośrednio jako usługa WGP, tabela hosting_wedos_protection).

Parametry:

  • status – opcjonalny, query – filtrowanie według określonego statusu usługi (wartość nie jest walidowana względem listy kodów statusów)

Kody zwrotne:

  • 1000 – OK

Dane odpowiedzi: Tablica usług; każdy element zawiera ID, name, status, expiration.

Przykład:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/wgp/services?status=active'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": [
    {
      "ID": 435,
      "name": "domain1.tld",
      "status": "active",
      "expiration": "2027-10-01 00:00:00"
    }
  ]
}

POST /services/{service_id}/cache/purge

Czyści pamięć podręczną CDN dla domeny podłączonej do WGP. Może dotyczyć samodzielnej usługi WGP albo domeny z WGP jako usługą dodatkową (hosting_domain); typ usługi ustawia się parametrem service_type .

Parametry:

  • service_id – wymagany, path – lokalne ID usługi
  • service_type – opcjonalny – typ usługi, hosting_wedos_protection (domyślnie) lub hosting_domain
  • limiter_decay – opcjonalny, liczba – czas w sekundach, przez który powtórne czyszczenie jest ograniczone; domyślnie 5
  • limiter_reset – opcjonalny, bool – anulowanie bieżącego limitu; domyślnie false

Kody zwrotne:

  • 1000 – OK
  • 2100 – brak wymaganego parametru
  • 2101 – nieprawidłowa wartość parametru
  • 2406 – nie znaleziono domeny/usługi
  • 2415 – limiter nadal działa – czyszczenia nie można teraz powtórzyć
  • 3223 – usługa należy do innego konta klienta
  • 2400 – błąd wewnętrzny – niezarejestrowany kod zwrotny

Dane odpowiedzi:

  • domain – nazwa domeny
  • domain_id – ID domeny w WGP
  • domain_tld – TLD domeny
  • service_id – ID usługi
  • wedos_client_id – ID klienta w WGP
  • limiter_available_in – za ile sekund funkcji można użyć ponownie (udokumentowane tylko dla błędu 2415; obecna implementacja nie zwraca jednak w razie błędu części data, patrz Uwagi)

Przykład:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/wgp/services/435/cache/purge' \
  --data '{"limiter_decay":5,"limiter_reset":0}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": {
    "domain": "domain1.tld",
    "domain_id": 98765,
    "domain_tld": "tld",
    "service_id": 435,
    "wedos_client_id": 10234
  }
}

POST /services/{service_id}/renew

Przedłuża usługę WGP na kolejny okres rozliczeniowy.

Parametry:

  • service_id – wymagany, path – ID usługi

Kody zwrotne:

  • 1000 – OK
  • 2100 – brak wymaganego parametru
  • 2101 – nieprawidłowa wartość parametru
  • 2152 – przedłużenie nie jest dozwolone w bieżącym stanie usługi
  • 2279 – konto kredytowe jest zablokowane
  • 2281 – konto kredytowe nie jest aktywne
  • 2282 – nie można zapłacić z konta kredytowego w podanej walucie
  • 2283 – niewystarczające saldo konta kredytowego
  • 2284 – błąd w danych kontaktowych konta kredytowego
  • 2293 – nie można pobrać salda konta kredytowego
  • 2297 – nie można ustalić, czy konto kredytowe zawiera VAT
  • 2406 – nie znaleziono usługi
  • 2409 – przedłużenie usługi nie powiodło się

Dane odpowiedzi:

  • service_id – ID usługi
  • name – nazwa domeny
  • date_from, date_to – daty obowiązywania nowego okresu
  • fakt_order_num – numer zamówienia przedłużenia
  • currency – waluta konta kredytowego
  • price – kwota przedłużenia
  • credit – saldo konta kredytowego po operacji (null dla usług FREE/TRIAL)

Przykład:

curl -X POST -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/wgp/services/435/renew'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": {
    "service_id": 435,
    "name": "domain1.tld",
    "date_from": "2027-10-01",
    "date_to": "2028-10-01",
    "fakt_order_num": "2026123457",
    "currency": "CZK",
    "price": 499,
    "credit": 502
  }
}

POST /services/{service_id}/template-replicate

Replikuje (stosuje) ustawienia domeny szablonowej do istniejącej domeny/usługi WGP.

Parametry:

  • service_id – wymagany, path – ID usługi, do której replikowane są ustawienia
  • template_domain_id – wymagany – ID domeny szablonowej (patrz GET /domains/templates)
  • service_type – opcjonalny – typ usługi, hosting_wedos_protection (domyślnie) lub hosting_domain

Kody zwrotne:

  • 1000 – OK
  • 2100 – brak wymaganego parametru
  • 2101 – nieprawidłowa wartość parametru
  • 2401 – nieprawidłowa domena do replikacji
  • 2402 – nieprawidłowa domena szablonowa
  • 2403 – niezgodność użytkownika między domeną a domeną szablonową
  • 2404 – niezgodność planu abonamentowego między domeną a domeną szablonową
  • 2405 – osiągnięto dzienny limit replikacji
  • 2406 – nie znaleziono domeny/usługi
  • 2407 – nie znaleziono domeny szablonowej
  • 2400 – błąd wewnętrzny – niezarejestrowany kod zwrotny

Dane odpowiedzi:

  • domain – nazwa domeny
  • domain_id – ID domeny
  • service_id – ID usługi
  • service_type – typ usługi
  • template_domain_id – ID użytej domeny szablonowej
  • replications_count – liczba dotychczas wykonanych replikacji
  • replications_limit – maksymalna dozwolona liczba replikacji

Przykład:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/wgp/services/435/template-replicate' \
  --data '{"template_domain_id":123}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": {
    "domain": "domain1.tld",
    "domain_id": 98765,
    "service_id": 435,
    "service_type": "hosting_wedos_protection",
    "template_domain_id": 123,
    "replications_count": 2,
    "replications_limit": 5
  }
}

PATCH /services/{service_id}

Zmienia wariant i/lub okres abonamentowy istniejącej usługi WGP.

Parametry:

  • service_id – wymagany, path – ID usługi
  • new_variant_id – opcjonalny, liczba – nowy wariant usługi
  • new_period_id – opcjonalny, liczba – nowy okres abonamentowy

Należy podać co najmniej jeden z parametrów new_variant_id/new_period_id .

Kody zwrotne:

  • 1000 – OK
  • 2100 – brak wymaganego parametru
  • 2101 – nieprawidłowa wartość parametru
  • 2203 – nieprawidłowa wartość new_period_id
  • 2273 – nieprawidłowa wartość new_variant_id
  • 2279 – konto kredytowe jest zablokowane
  • 2281 – konto kredytowe nie jest aktywne
  • 2282 – nie można zapłacić z konta kredytowego w podanej walucie
  • 2283 – niewystarczające saldo konta kredytowego
  • 2284 – błąd w danych kontaktowych konta kredytowego
  • 2293 – nie można pobrać salda konta kredytowego
  • 2294 – nie można pobrać ceny usługi
  • 2406 – nie znaleziono domeny/usługi
  • 2408 – parametr new_variant_id lub new_period_id nie został podany (nie podano żadnego z nich)
  • 2400 – błąd wewnętrzny – niezarejestrowany kod zwrotny

Dane odpowiedzi:

  • domain – nazwa domeny
  • domain_id – ID domeny
  • wedos_client_id – ID klienta w WGP
  • service_id – ID usługi
  • service_type – typ usługi
  • variant_id – bieżące ID wariantu usługi po zmianie
  • period_id – bieżące ID okresu abonamentowego po zmianie
  • dirty – flaga wskazująca, czy zmiana rzeczywiście nastąpiła (0 = bez zmian, 1 = zmieniono)

Przykład:

curl -X PATCH -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/wgp/services/435' \
  --data '{"new_variant_id":2,"new_period_id":1}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": {
    "domain": "domain1.tld",
    "domain_id": 98765,
    "wedos_client_id": 10234,
    "service_id": 435,
    "service_type": "hosting_wedos_protection",
    "variant_id": 2,
    "period_id": 1,
    "dirty": 1
  }
}

DELETE /services/{service_id}

Usuwa/kończy usługę WGP na żądanie klienta.

Parametry:

  • service_id – wymagany, path – ID usługi
  • force – opcjonalny, query, 0/1 – wymusza usunięcie nawet wtedy, gdy WGP nie dysponuje tokenem do przepisania DNS (przywrócenia rekordów A/AAAA do pierwotnych wartości)

Kody zwrotne:

  • 1000 – OK
  • 2100 – brak wymaganego parametru
  • 2292 – nie znaleziono domeny w WGP dla tego konta klienta
  • 2400 – błąd wewnętrzny
  • 2410 – nie znaleziono usługi
  • 2411 – brak tokenu do przepisania DNS
  • 2412 – żądanie API przepisania DNS nie powiodło się
  • 2413 – polecenia nie można wykonać, WGP nie ma uprawnień do manipulowania DNS domeny (force=1 wymagane)
  • 2414 – nie istnieje token dla WGP, a parametr force nie został podany
  • 3223 – usługa należy do innego konta klienta

Dane odpowiedzi:

  • domain – nazwa domeny
  • domain_id – ID domeny
  • wedos_client_id – ID klienta w WGP
  • service_id – ID usługi
  • service_type – typ usługi
  • wdns_data – tablica wykonanych zmian rekordów DNS (adresy IP, które po anulowaniu WGP przestają być kierowane przez WGP)

Przykład:

curl -X DELETE -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/wgp/services/435?force=1'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": {
    "domain": "domain1.tld",
    "domain_id": 98765,
    "wedos_client_id": 10234,
    "service_id": 435,
    "service_type": "hosting_wedos_protection",
    "wdns_data": []
  }
}

Uwagi

  • GET /services zwraca wyłącznie samodzielne usługi WGP. Domeny, do których WGP jest podłączone jako dodatek do innej usługi, nie znajdują się na tej liście i nie istnieje dla nich podobny endpoint listujący.
  • POST /services/{service_id}/cache/purge oraz POST /services/{service_id}/template-replicate są adresowane bezpośrednio przez service_id (a nie przez domenę) i obsługują parametr service_type, który pozwala odróżnić samodzielną usługę WGP od domeny z WGP jako dodatkiem. Odpowiednie polecenie WAPI samo wyszukuje właściciela po user_id.
  • W przypadku POST /services/{service_id}/cache/purge komentarz dokumentacyjny funkcji cmd_purge_cache() wspomina także o polu limiter_available_in w danych odpowiedzi dla błędu 2415, ale obecna implementacja zwraca w tym przypadku wyłącznie sam kod błędu bez części data – pole nie pojawia się więc w odpowiedzi.

Czy to było pomocne?

Dziękujemy za opinię!
Selektory ogólne
Tylko dokładne dopasowania
Szukaj w tytule
Szukaj w treści
Selektory typów wpisów
Spis treści artykułu
Przeglądaj kategorie