REST API – Podręcznik

W tym artykule można dowiedzieć się:

• Jak działa WEDOS REST API
• Jakie są dostępne endpointy
• Jak zarządzać klientami API
• Jak działa rejestrowanie żądań API
• Najczęściej zadawane pytania

---

Funkcje WEDOS REST API

HTTP REST API v2 umożliwia zarządzanie usługami WEDOS z własnych aplikacji i skryptów. Cała komunikacja odbywa się przez HTTPS pod adresem https://api.wedos.com, a dane są wysyłane i zwracane w formacie JSON.

Aby uzyskać dostęp do API, należy utworzyć klienta API z uprawnieniami dostępu (do odczytu i zapisu albo tylko do odczytu – patrz rozdział Zarządzanie klientami ) do jednego lub kilku endpointów (patrz Endpointy). Każde żądanie jest rejestrowane (patrz Rejestrowanie żądań).

Limit żądań

• Domyślny limit to 1 000 żądań na godzinę na jednego klienta API. Każdy klient ma własny limit, wspólny dla wszystkich API (domains, wdns, wgp, …).
• Do limitu wliczają się wszystkie żądania, w tym odrzucone.
• Aktualny limit jest widoczny na liście klientów w panelu administracyjnym.
• Jeśli limit okaże się niewystarczający, należy skontaktować się z obsługą klienta za pośrednictwem formularza ⧉. Należy podać żądany limit oraz uzasadnienie, dlaczego ma zostać ustawiony. Dla danego konta możemy go indywidualnie zwiększyć.

HTTP REST API vs. WAPI

WEDOS oferuje dwa API: starsze WAPI i nowsze HTTP REST API v2. Można je porównać za pomocą poniższej tabeli:

	WAPI	HTTP REST API v2
Uwierzytelnianie	Jeden login i hasło WAPI dla całego konta	Osobny klient API z własnym tokenem dla każdej aplikacji lub osoby
Ograniczenia dostępu	Wymagana lista adresów IP dla całego konta	Uprawnienia (scopes), „Tylko do odczytu”, adresy IP i ważność tokenu, ustawiane osobno dla każdego klienta
Format	XML lub JSON, jeden endpoint, polecenia w treści żądania	REST (metody HTTP i adresy URL), JSON
Zakres	Szeroki wachlarz poleceń dla usług WEDOS	domeny, kontakty, NSSET-y, WEDOS DNS, WEDOS Global Protection
Log	Jeden log dla całego konta	Log identyfikujący klienta API

Zalecamy używanie:

• HTTP REST API v2 do nowych integracji, jeśli obejmuje potrzebne operacje, oraz wszędzie tam, gdzie trzeba oddzielić dostęp poszczególnych osób lub systemów, ograniczyć go tylko do odczytu albo prześledzić, kto co zrobił (audyt, DORA).
• WAPI do operacji, których HTTP REST API v2 jeszcze nie oferuje.

Aby przejść z WAPI na WEDOS REST API, należy wykonać następujące kroki:

1. W panelu administracyjnym należy utworzyć dla każdej aplikacji lub systemu klienta API z wymaganymi uprawnieniami (scopes). Wskazówki znajdują się w rozdziale Zarządzanie klientami .
2. Wywołania poleceń WAPI należy zastąpić odpowiadającymi im endpointami z dokumentacji poszczególnych API. Patrz rozdział Endpointy .
3. Kody wyniku operacji (na przykład 1000 OK, 3201 domena jest już zarejestrowana) są takie same jak w WAPI, ponieważ HTTP REST API v2 wykonuje te same operacje. Dodatkowo istnieją ogólne kody warstwy REST (na przykład 2000 brak tokenu lub nieprawidłowy token, 2012 klient tylko do odczytu), opisane w dokumentacji poszczególnych API.
4. W okresie przejściowym można używać obu API jednocześnie.

---

Endpointy

WEDOS REST API umożliwia automatyzację zarządzania następującymi obszarami:

• Domeny: Endpointy /domains/ zajmują się rejestracją, transferami i odnowieniami domen. Potrafią także wysyłać AUTH-ID oraz ustawiać serwery DNS/NSSET i KEYSET dla DNSSEC. Ich zakres uprawnień (scope) to domains. Więcej informacji zawiera artykuł REST API – Domeny .
• Kontakty domen: Endpointy /contacts/ tworzą kontakty domen i zarządzają nimi. Dla domen .cz dostępne są transfery. Ich zakres uprawnień (scope) to domains. Więcej informacji zawiera artykuł REST API – Kontakty domen .
• NSSET-y: Endpointy /nssets/ tworzą obiekty NSSET stowarzyszenia CZ.NIC i zarządzają nimi. Ich zakres uprawnień (scope) to domains. Więcej informacji zawiera artykuł REST API – NSSET-y domen .
• DNS: Endpoint /dns/ tworzy domeny DNS oraz poszczególne rekordy i zarządza nimi. Obejmuje to importy do podstawowego DNS oraz AXFR dla zapasowego DNS. Jego zakres uprawnień (scope) to dns. Więcej informacji zawiera artykuł REST API – DNS .
• WEDOS.protection: Endpoint /wgp/ endpointy tworzą usługi WEDOS.protection i nimi zarządzają. Ich zakres uprawnień (scope) to wgp. Więcej informacji zawierają artykuły REST API – WGP Domains, REST API – WGP Services i REST API – WGP Members.

---

Zarządzanie klientami

Dostęp do API konfiguruje się w panelu administracyjnym klienta, w sekcji HTTP REST API . Dla każdej aplikacji, systemu lub osoby należy utworzyć osobnego klienta API . Dla każdego klienta ustawia się:

• Uprawnienia (scopes): do których API klient ma dostęp,
• Tylko do odczytu: klient może jedynie wyświetlać informacje (patrz niżej),
• Filtrowanie adresów IP: dozwolone lub zablokowane adresy IP, z których klient może wywoływać API,
• Ważność tokenu: kiedy access token zaczyna obowiązywać i kiedy wygasa.

Klient uwierzytelnia się access tokenem w nagłówku Authorization: Bearer <TOKEN> . Token można wygenerować bezpośrednio w panelu administracyjnym albo aplikacja może pobrać go sama przy użyciu client ID i client secret (patrz rozdział OAuth2 ).

Tworzenie nowego klienta

Nowego klienta można utworzyć tylko w panelu administracyjnym klienta. Należy wykonać następujące kroki:

1. Zalogować się do panelu administracyjnego klienta.
2. Przejść do interfejsu WEDOS REST API (obecnie niedostępny).
3. Kliknąć przycisk Nowy klient .
4. Wypełnić pole Nazwa klienta (krótka nazwa identyfikująca klienta na liście) i wybrać jeden lub więcej obszarów uprawnień z menu Wybierz uprawnienia . Dostępne obszary odpowiadają endpointom.
5. Opcjonalnie można wprowadzić dalsze ustawienia:
   • Zaznaczyć dostęp Tylko do odczytu . Klient może wtedy jedynie pobierać informacje. Żądania, które dodają, aktualizują lub usuwają elementy, są blokowane.
   • W sekcji Ważność tokenuwybrać, jak długo token pozostaje ważny od momentu wydania: Bez wygaśnięcia, 7 dni, 30 dni, 90 dni, 1 rok lub Własna. Pola Ważny od i Wygaśnięcie pokazują wynikowe daty.
   • W sekcji Ograniczenia bezpieczeństwamożna opcjonalnie włączyć Filtrowanie adresów IP i wprowadzić dozwolony adres IP. Aby dodać kolejne adresy, należy kliknąć + Dodaj kolejny , albo × w celu usunięcia adresu. Po włączeniu filtrowania API przyjmuje żądania tylko z wymienionych adresów.

Po zakończeniu konfiguracji należy ją potwierdzić przyciskiem Utwórz klienta .

Nowy klient pojawia się na liście ze swoją nazwą, uprawnieniami, typem dostępu (na przykład read, write), datami ważności i statusem. Listę można filtrować według tych pozycji: Uprawnienia, Status, Ważność i Dostęp.

Client Secret

Zaraz po utworzeniu klienta pojawia się okno Tajny klucz klienta z komunikatem Skopiuj tajny klucz i zapisz go w bezpiecznym miejscu.

1. Kliknąć Kopiuj obok tajnego klucza.
2. Zapisać tajny klucz w bezpiecznym miejscu, na przykład w menedżerze haseł lub w magazynie sekretów na serwerze.
3. Kliknąć Rozumiem, zamknij.

Tajny klucz jest wyświetlany tylko w tym oknie, dlatego należy go zapisać przed jego zamknięciem. Razem z client ID jest potrzebny do pobierania tokenów przez API (patrz rozdział OAuth2).

Zarządzanie istniejącym klientem

Stronę Konfiguracja HTTP REST API klienta otwiera się, klikając ikonę edycji obok jego nazwy na liście. Można zmienić dowolne ustawienia wprowadzone podczas tworzenia, w tym nazwę i uprawnienia.

Client ID i Client Secret nie podlegają edycji.

Podczas zarządzania istniejącym klientem dostępne są następujące elementy sterujące:

• Zapisz zmiany: zapisuje zmiany w ustawieniach klienta.
• Wyłącz: dezaktywuje (blokuje) klienta bez jego usuwania.
• Usuń: trwale usuwa klienta.
• Powrót do listy HTTP REST API: powrót do listy klientów.
• Odśwież: ponownie wczytuje stronę.

Bearer token klienta

Pole Bearer token służy do identyfikacji klienta podczas dostępu do endpointów. Pokazuje aktualny access token klienta. Kliknięcie Kopiuj pozwala go skopiować.

Token wymienia się, klikając Nowy token. Stary token natychmiast przestaje działać, dlatego należy zaktualizować wszystkie aplikacje, które go używają.

Sekcja Przykład (curl) pokazuje gotowe żądanie z aktualnym tokenem do celów testowych.

OAuth2

Aplikacja może pobrać własny token pod adresem POST https://api.wedos.com/oauth2/token przy użyciu client ID i tajnego klucza. Każda inna metoda HTTP zwraca błąd.

• Client ID: W interfejsie zarządzania klientamikliknąć Pokaż Client ID , aby wyświetlić client ID, a następnie kliknąć Kopiuj.
• Client Secret: Tajny klucz jest dostępny tylko po utworzeniu konta. Więcej informacji znajduje się w rozdziale Client Secret .

Należy użyć jednej z dwóch metod:

• HTTP Basic (zalecane): nagłówek Authorization: Basic <base64(client_id:client_secret)>. curl tworzy go automatycznie przy użyciu -u 'client_id:client_secret'.
• W treści żądania: parametry client_id i client_secret.

Parametry należy wysyłać w treści jako application/x-www-form-urlencoded, albo jako JSON z nagłówkiem Content-Type: application/json.

Parametr	Wymagany	Opis
grant_type	Tak	Zawsze client_credentials
scope	Nie	Uprawnienia (scopes) oddzielone spacją spośród: domains (obejmuje kontakty domen i NSSET), wdns i wgp. Musi to być podzbiór scopes klienta. W przypadku pominięcia token otrzymuje wszystkie scopes klienta.
client_id, client_secret	Tylko bez HTTP Basic	Dane uwierzytelniające klienta

Przykład: HTTP Basic (zalecane)

curl -X POST -u '<CLIENT_ID>:<CLIENT_SECRET>' \
  -d 'grant_type=client_credentials' \
  -d 'scope=domains' \
  'https://api.wedos.com/oauth2/token'

Przykład: Dane uwierzytelniające w treści żądania

curl -X POST \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<CLIENT_ID>' \
  -d 'client_secret=<CLIENT_SECRET>' \
  -d 'scope=domains' \
  'https://api.wedos.com/oauth2/token'

Przykład: JSON

curl -X POST -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"<CLIENT_ID>","client_secret":"<CLIENT_SECRET>","scope":"domains"}' \
  'https://api.wedos.com/oauth2/token'

Pole code ma wartość 1000 przy wydaniu tokenu lub 2000 przy błędzie uwierzytelnienia klienta albo nieprawidłowym żądaniu.

W przypadku powodzenia data zawiera:

Pole	Opis
access_token	Token wysyłany jako Authorization: Bearer <TOKEN>
token_type	Typ tokenu (Bearer)
expires_in	Ważność w sekundach (domyślnie 3600, tj. 1 godzina)
scope	Scopes, które token faktycznie otrzymał

{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": {
    "access_token": "3f9c2e7a1b...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "domains"
  }
}

Dla client_credentialsnie jest wydawany refresh token. Po wygaśnięciu tokenu należy pobrać nowy tym samym wywołaniem.

W przypadku błędu data zawiera status_code (status HTTP OAuth2, np. 400 lub 401), error i error_description.

error	Przyczyna
invalid_client	Nieprawidłowy client_id lub client_secret, albo klient jest zablokowany
invalid_request	grant_type lub inna wymagana wartość jest nieobecna, albo metoda nie była POST
unsupported_grant_type	Nieobsługiwana wartość parametru grant_type .
invalid_scope	Żądany scope nie istnieje lub nie jest przypisany do klienta

{
  "code": 2000,
  "msg": "API method error - Bad Request",
  "request_id": "a1b2c3d5",
  "data": {
    "status_code": 400,
    "error": "invalid_client",
    "error_description": "The client credentials are invalid"
  }
}

Wartość data.access_token należy wysyłać w nagłówku Authorization przy wywoływaniu dowolnego endpointu v2 objętego scope tokenu.

Przykład:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/domains'

Warto przestrzegać następujących dobrych praktyk:

• Token należy zapisać i używać go ponownie, dopóki nie wygaśnie jego ważność (expires_in). Nie należy pobierać nowego tokenu przed każdym wywołaniem API.
• Jeśli endpoint v2 zwróci błąd uwierzytelnienia (2000), należy pobrać nowy token i powtórzyć wywołanie.
• Należy żądać tylko tych scopes, których potrzebuje aplikacja, oraz używać Tylko do odczytu dla klientów, którzy nigdy nie zmieniają danych.
• Tam, gdzie to możliwe, należy ograniczyć każdego klienta do znanych adresów IP.
• Dla każdej aplikacji należy utworzyć osobnego klienta, aby móc wyłączyć lub usunąć jednego bez wpływu na pozostałych.

Zalecana konfiguracja dla zespołów

Jeśli dostęp do API ma więcej osób, zalecamy następującą konfigurację:

• Jeden klient API na osobę lub system. Z logu wynika, kto wykonał poszczególne żądania, a gdy ktoś odchodzi, blokuje się tylko jego klienta.
• Tylko potrzebne scopes. Klient do obsługi DNS nie potrzebuje dostępu do domen.
• „Tylko do odczytu” wszędzie tam, gdzie to wystarcza – monitoring, raporty, kontrole statusu.
• Ograniczenie do adresów IP serwerów lub sieci, które faktycznie wywołują API.
• Wygasanie tokenu. Należy ustawić okres ważności i regularnie odnawiać token.
• Tajny klucz klienta należy przechowywać wyłącznie po stronie serwera – nigdy w przeglądarce, aplikacji mobilnej ani w publicznym repozytorium.

Gdy ktoś odchodzi:

1. Należy zablokować lub usunąć jego klienta API na liście klientów. Wszystkie jego tokeny natychmiast przestają działać i nie można dla niego pobrać nowego tokenu. Nie ma to wpływu na pozostałych klientów.
2. Jeśli jego pracę przejmuje ktoś inny, zawsze należy utworzyć nowego klienta dla tej osoby.

---

Rejestrowanie żądań

Sekcja HTTP REST API w panelu administracyjnym zawiera log żądań. Można go filtrować według uprawnień (scope), klienta API, statusu i metody HTTP.

Aby uzyskać dostęp do logu, należy wykonać następujące kroki:

1. Zalogować się do panelu administracyjnego klienta.
2. Przejść do interfejsu WEDOS REST API (obecnie niedostępny).
3. Kliknąć przycisk Wyświetl log żądań HTTP REST API .

Każdy klient na liście ma dodatkowo odnośnik log , który otwiera log odfiltrowany do żądań tego klienta.

Przy każdym żądaniu rejestrujemy:

• datę i godzinę oraz adres IP, z którego przyszło żądanie,
• klienta API (ID i nazwę) oraz uprawnienia (scope),
• metodę HTTP, URL i wykonane polecenie,
• dane wejściowe i odpowiedź API (wynik i kod zwrotny).

Nie rejestrujemy:

• access tokenu ani tajnego klucza klienta – nagłówek Authorization nie jest zapisywany w logu żądań, a token jest maskowany w wewnętrznych zapisach WEDOS,
• wrażliwe wartości w danych wejściowych (hasła i podobne) są zapisywane w postaci zamaskowanej.

Inne ważne informacje:

• Dane wejściowe i odpowiedź są przechowywane łącznie do 1 024 znaków. Dłuższa treść jest obcinana.
• Zapisy są przechowywane przez 90 dni, po czym są automatycznie usuwane.
• Logu nie można jeszcze eksportować ani odczytywać przez API. Jest dostępny tylko w panelu administracyjnym klienta.

---

Najczęściej zadawane pytania