REST API – Manuál

V tomto článku sa dozviete:

• Ako WEDOS REST API funguje
• Aké sú dostupné endpointy
• Ako spravovať API klientov
• Ako funguje logovanie API požiadaviek
• Často kladené otázky

---

Vlastnosti WEDOS REST API

HTTP REST API v2 umožňuje spravovať vaše služby WEDOS z vlastných aplikácií a skriptov. Všetka komunikácia prebieha cez HTTPS na adrese https://api.wedos.com, dáta sa odosielajú a vracajú vo formáte JSON.

Na získanie prístupu k API je potrebné vytvoriť API klienta s prístupovými oprávneniami (na čítanie aj zápis, alebo iba na čítanie – pozrite kapitolu Správa klientov ) k jednému alebo viacerým endpointom (pozrite Endpointy). Každá požiadavka sa zaznamenáva (pozrite Logovanie požiadaviek).

Limit požiadaviek

• Predvolený limit je 1 000 požiadaviek za hodinu na jedného API klienta. Každý klient má vlastný limit, zdieľaný naprieč všetkými API (domains, wdns, wgp, …).
• Do limitu sa započítavajú všetky požiadavky vrátane odmietnutých.
• Aktuálny limit je uvedený v zozname klientov v administrácii.
• Ak vám limit nestačí, kontaktujte zákaznícku podporu prostredníctvom formulára ⧉. Uveďte požadovaný limit a dôvod, prečo ho chcete nastaviť. Pre váš účet ho môžeme individuálne navýšiť.

HTTP REST API vs. WAPI

WEDOS ponúka dve API: staršie WAPI a novšie HTTP REST API v2. Porovnať ich môžete pomocou nasledujúcej tabuľky:

	WAPI	HTTP REST API v2
Autentizácia	Jedno prihlasovacie meno a WAPI heslo pre celý účet	Samostatný API klient s vlastným tokenom pre každú aplikáciu alebo osobu
Obmedzenie prístupu	Povinný zoznam IP adries pre celý účet	Oprávnenia (scopes), „Iba na čítanie“, IP adresy a platnosť tokenu, nastavené pre každého klienta zvlášť
Formát	XML alebo JSON, jediný endpoint, príkazy v tele požiadavky	REST (HTTP metódy a URL), JSON
Pokrytie	Široká škála príkazov pre služby WEDOS	domény, kontakty, NSSETy, WEDOS DNS, WEDOS Global Protection
Log	Jeden log pre celý účet	Log, ktorý identifikuje API klienta

Odporúčame používať:

• HTTP REST API v2 pre nové integrácie, ak pokrýva operácie, ktoré potrebujete, a všade tam, kde potrebujete oddeliť prístup jednotlivých osôb alebo systémov, obmedziť ich iba na čítanie alebo dohľadať, kto čo urobil (audit, DORA).
• WAPI pre operácie, ktoré HTTP REST API v2 zatiaľ neponúka.

Ak chcete prejsť z WAPI na WEDOS REST API, postupujte takto:

1. V administrácii vytvorte pre každú aplikáciu alebo systém API klienta s potrebnými oprávneniami (scopes). Návod nájdete v kapitole Správa klientov .
2. Nahraďte volania príkazov WAPI zodpovedajúcimi endpointmi z dokumentácie jednotlivých API. Pozrite kapitolu Endpointy .
3. Kódy výsledku operácie (napríklad 1000 OK, 3201 doména je už zaregistrovaná) sú rovnaké ako vo WAPI, pretože HTTP REST API v2 vykonáva tie isté operácie. Navyše existujú všeobecné kódy REST vrstvy (napríklad 2000 chýbajúci alebo neplatný token, 2012 klient iba na čítanie), popísané v dokumentácii jednotlivých API.
4. Počas prechodu môžete obe API používať súčasne.

---

Endpointy

WEDOS REST API umožňuje automatizovať správu týchto oblastí:

• Domény: Endpointy /domains/ zabezpečujú registráciu, transfery a predĺženie domén. Vedia tiež odosielať AUTH-ID a nastavovať DNS servery/NSSET a KEYSET pre DNSSEC. Ich oprávnenie (scope) je domains. Viac informácií nájdete v článku REST API – Domény .
• Kontakty domén: Endpointy /contacts/ vytvárajú a spravujú kontakty domén. Pre domény .cz sú k dispozícii transfery. Ich oprávnenie (scope) je domains. Viac informácií nájdete v článku REST API – Kontakty domén .
• NSSETy: Endpointy /nssets/ vytvárajú a spravujú objekty NSSET združenia CZ.NIC. Ich oprávnenie (scope) je domains. Viac informácií nájdete v článku REST API – NSSETy domén .
• DNS: Endpoint /dns/ vytvára a spravuje DNS domény aj jednotlivé záznamy. Zahŕňa to importy do primárneho DNS a AXFR pre sekundárne DNS. Jeho oprávnenie (scope) je dns. Viac informácií nájdete v článku REST API – DNS .
• WEDOS.protection: Endpoint /wgp/ endpointy vytvárajú a spravujú služby WEDOS.protection. Ich oprávnenie (scope) je wgp. Viac informácií nájdete v článkoch REST API – WGP Domains, REST API – WGP Services a REST API – WGP Members.

---

Správa klientov

Prístup k API nastavíte v zákazníckej administrácii v sekcii HTTP REST API . Pre každú aplikáciu, systém alebo osobu vytvorte samostatného API klienta . U každého klienta nastavíte:

• Oprávnenia (scopes): ku ktorým API má klient prístup,
• Iba na čítanie: klient môže informácie iba zobrazovať (pozrite nižšie),
• Filtrovanie IP adries: povolené alebo blokované IP adresy, z ktorých klient môže API volať,
• Platnosť tokenu: kedy začne access token platiť a kedy vyprší.

Klient sa autentizuje access tokenom v hlavičke Authorization: Bearer <TOKEN> . Token môžete vygenerovať priamo v administrácii, alebo si ho vaša aplikácia môže vyžiadať sama pomocou client ID a client secret (pozrite kapitolu OAuth2 ).

Vytvorenie nového klienta

Nového klienta možno vytvoriť iba v zákazníckej administrácii. Postupujte takto:

1. Prihláste sa do zákazníckej administrácie.
2. Prejdite do rozhrania WEDOS REST API (aktuálne nedostupné).
3. Kliknite na tlačidlo Nový klient .
4. Zadajte Názov klienta (krátky názov, ktorý klienta identifikuje v zozname) a vyberte jednu alebo viac oblastí oprávnení z ponuky Vybrať oprávnenia . Dostupné oblasti zodpovedajú endpointom.
5. Voliteľne vykonajte ďalšie nastavenia:
   • Začiarknite prístup Iba na čítanie . Klient potom môže informácie iba vyžadovať. Požiadavky, ktoré položky pridávajú, upravujú alebo mažú, sú blokované.
   • V časti Platnosť tokenuzvoľte, ako dlho token zostane platný po svojom vydaní: Bez expirácie, 7 dní, 30 dní, 90 dní, 1 rok alebo Vlastné. Polia Platné od a Expirácia zobrazujú výsledné dátumy.
   • V časti Bezpečnostné obmedzeniamôžete voliteľne zapnúť Filtrovanie IP adries a zadať povolenú IP adresu. Pre ďalšie adresy kliknite na + Pridať ďalšiu , alebo na × pre odobranie adresy. Ak je filtrovanie zapnuté, API prijíma požiadavky iba z uvedených adries.

Po dokončení nastavenia ho potvrďte tlačidlom Vytvoriť klienta .

Nový klient sa objaví v zozname so svojím názvom, oprávneniami, typom prístupu (napríklad read, write), dátumami platnosti a stavom. Zoznam môžete filtrovať podľa týchto položiek: Oprávnenia, Stav, Platnosť a Prístup.

Client Secret

Ihneď po vytvorení klienta sa zobrazí dialóg Tajný kľúč klienta so správou Skopírujte tajný kľúč a uložte ho na bezpečné miesto.

1. Kliknite na Kopírovať vedľa tajného kľúča.
2. Uložte tajný kľúč na bezpečné miesto, napríklad do správcu hesiel alebo do úložiska tajných údajov na vašom serveri.
3. Kliknite na Rozumiem, zavrieť.

Tajný kľúč sa zobrazí iba v tomto dialógu, preto ho uložte skôr, než dialóg zavriete. Spolu s client ID ho potrebujete na vyžiadanie tokenov cez API (pozrite kapitolu OAuth2).

Správa existujúceho klienta

Stránku Nastavenie HTTP REST API klienta otvoríte kliknutím na ikonu úprav vedľa jeho názvu v zozname. Môžete upraviť ľubovoľné nastavenie zadané pri vytváraní, vrátane názvu a oprávnení.

Client ID a Client Secret upraviť nemožno.

Pri správe existujúceho klienta sú k dispozícii tieto ovládacie prvky:

• Uložiť zmeny: Uloží zmeny v nastavení klienta.
• Zakázať: Deaktivuje (zablokuje) klienta bez jeho zmazania.
• Zmazať: Trvalo klienta odstráni.
• Späť na zoznam HTTP REST API: Návrat na zoznam klientov.
• Obnoviť: Znovu načíta stránku.

Bearer token klienta

Pole Bearer token slúži na identifikáciu klienta pri prístupe k endpointom. Zobrazuje aktuálny access token klienta. Kliknutím na Kopírovať ho skopírujete.

Token nahradíte kliknutím na Nový token. Starý token okamžite prestane fungovať, preto aktualizujte všetky aplikácie, ktoré ho používajú.

Sekcia Príklad (curl) zobrazuje pripravenú požiadavku s aktuálnym tokenom na testovacie účely.

OAuth2

Vaša aplikácia si môže vyžiadať vlastný token na POST https://api.wedos.com/oauth2/token pomocou client ID a tajného kľúča. Akákoľvek iná HTTP metóda vráti chybu.

• Client ID: V rozhraní pre správu klientovkliknite na Zobraziť Client ID , čím client ID zobrazíte, a potom kliknite na Kopírovať.
• Client Secret: Tajný kľúč je dostupný iba po vytvorení účtu. Viac informácií nájdete v kapitole Client Secret .

Použite jednu z dvoch metód:

• HTTP Basic (odporúčané): hlavička Authorization: Basic <base64(client_id:client_secret)>. curl ju za vás zostaví pomocou -u 'client_id:client_secret'.
• V tele požiadavky: parametre client_id a client_secret.

Parametre odosielajte v tele ako application/x-www-form-urlencoded, alebo ako JSON s hlavičkou Content-Type: application/json.

Parameter	Povinný	Popis
grant_type	Áno	Vždy client_credentials
scope	Nie	Oprávnenia (scopes) oddelené medzerou z týchto možností: domains (zahŕňa kontakty domén a NSSET), wdns a wgp. Musí ísť o podmnožinu scopes klienta. Ak je parameter vynechaný, token získa všetky scopes klienta.
client_id, client_secret	Iba bez HTTP Basic	Prihlasovacie údaje klienta

Príklad: HTTP Basic (odporúčané)

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

Príklad: Prihlasovacie údaje v tele požiadavky

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'

Príklad: 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 má hodnotu 1000 pri vydaní tokenu, alebo 2000 pri chybe autentizácie klienta či neplatnej požiadavke.

Pri úspechu data obsahujú:

Pole	Popis
access_token	Token, odosielaný ako Authorization: Bearer <TOKEN>
token_type	Typ tokenu (Bearer)
expires_in	Platnosť v sekundách (predvolene 3600, t. j. 1 hodina)
scope	Scopes, ktoré token skutočne získal

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

Refresh token sa pre client_credentialsnevydáva. Po vypršaní platnosti tokenu si vyžiadajte nový rovnakým volaním.

Pri chybe data obsahujú status_code (HTTP status OAuth2, napr. 400 alebo 401), error a error_description.

error	Príčina
invalid_client	Neplatný client_id alebo client_secret, alebo je klient zablokovaný
invalid_request	grant_type alebo iná povinná hodnota chýba, prípadne metóda nebola POST
unsupported_grant_type	Nepodporovaná hodnota parametra grant_type .
invalid_scope	Požadovaný scope neexistuje alebo nie je klientovi priradený

{
  "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"
  }
}

Hodnotu data.access_token odosielajte v hlavičke Authorization pri volaní ľubovoľného endpointu v2, ktorý spadá do scope tokenu.

Príklad:

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

Snažte sa dodržiavať tieto odporúčané postupy:

• Token si uložte a používajte ho opakovane, kým nevyprší jeho platnosť (expires_in). Nežiadajte o nový token pred každým volaním API.
• Ak endpoint v2 vráti chybu autentizácie (2000), vyžiadajte si nový token a volanie zopakujte.
• Žiadajte iba o scopes, ktoré vaša aplikácia potrebuje, a použite Iba na čítanie u klientov, ktorí nikdy nemenia dáta.
• Kde je to možné, obmedzte každého klienta na známe IP adresy.
• Pre každú aplikáciu vytvorte samostatného klienta, aby ste mohli jedného zakázať alebo zmazať bez vplyvu na ostatných.

Odporúčané nastavenie pre tímy

Ak má k API prístup viac osôb, odporúčame toto nastavenie:

• Jeden API klient na osobu alebo systém. Z logu je zrejmé, kto ktorú požiadavku vykonal, a keď niekto odíde, zablokujete iba jeho klienta.
• Iba potrebné scopes. Klient pre DNS nepotrebuje prístup k doménam.
• „Iba na čítanie“, kdekoľvek to stačí – monitoring, reporty, kontroly stavu.
• Obmedzenie na IP adresy serverov alebo sietí, ktoré API skutočne volajú.
• Expirácia tokenu. Nastavte dobu platnosti a token pravidelne obnovujte.
• Tajný kľúč klienta uchovávajte iba na strane servera – nikdy nie v prehliadači, v mobilnej aplikácii ani vo verejnom repozitári.

Keď niekto odíde:

1. Zablokujte alebo zmažte jeho API klienta v zozname klientov. Všetky jeho tokeny okamžite prestanú fungovať a nový token preň nemožno vyžiadať. Ostatných klientov sa to nedotkne.
2. Ak jeho prácu preberá niekto iný, vždy vytvorte nového klienta pre túto osobu.

---

Logovanie požiadaviek

Sekcia HTTP REST API v administrácii obsahuje log požiadaviek. Môžete ho filtrovať podľa oprávnenia (scope), API klienta, stavu a HTTP metódy.

Na prístup k logu postupujte takto:

1. Prihláste sa do zákazníckej administrácie.
2. Prejdite do rozhrania WEDOS REST API (aktuálne nedostupné).
3. Kliknite na tlačidlo Zobraziť log požiadaviek HTTP REST API .

Každý klient v zozname má navyše odkaz log , ktorý otvorí log filtrovaný na požiadavky tohto klienta.

Pri každej požiadavke zaznamenávame:

• dátum a čas a IP adresu, z ktorej požiadavka prišla,
• API klienta (ID a názov) a oprávnenie (scope),
• HTTP metódu, URL a vykonaný príkaz,
• vstupné dáta a odpoveď API (výsledok a návratový kód).

Nezaznamenávame:

• access token ani tajný kľúč klienta – hlavička Authorization sa v logu požiadaviek neukladá a token je v interných záznamoch WEDOS maskovaný,
• citlivé hodnoty vo vstupných dátach (heslá a podobne) sa ukladajú maskované.

Ďalšie dôležité informácie:

• Vstupné dáta a odpoveď sa ukladajú spolu do 1 024 znakov. Dlhší obsah je skrátený.
• Záznamy sa uchovávajú 90 dní, potom sú automaticky zmazané.
• Log zatiaľ nemožno exportovať ani čítať cez API. Je dostupný iba v zákazníckej administrácii.

---

Často kladené otázky