REST API – Manuál

V tomto článku se dozvíte:

• Jak WEDOS REST API funguje
• Jaké jsou dostupné endpointy
• Jak spravovat API klienty
• Jak funguje logování API požadavků
• Často kladené otázky

---

Vlastnosti WEDOS REST API

HTTP REST API v2 umožňuje spravovat vaše služby WEDOS z vlastních aplikací a skriptů. Veškerá komunikace probíhá přes HTTPS na adrese https://api.wedos.com, data se odesílají a vracejí ve formátu JSON.

Pro získání přístupu k API je potřeba vytvořit API klienta s přístupovými oprávněními (pro čtení i zápis, nebo pouze pro čtení – viz kapitolu Správa klientů ) k jednomu nebo více endpointům (viz Endpointy). Každý požadavek je zaznamenán (viz Logování požadavků).

Limit požadavků

• Výchozí limit je 1 000 požadavků za hodinu na jednoho API klienta. Každý klient má vlastní limit, sdílený napříč všemi API (domains, wdns, wgp, …).
• Do limitu se započítávají všechny požadavky, včetně odmítnutých.
• Aktuální limit je uveden v seznamu klientů v administraci.
• Pokud vám limit nestačí, kontaktujte zákaznickou podporu prostřednictvím formuláře ⧉. Uveďte požadovaný limit a důvod, proč jej chcete nastavit. Pro váš účet jej můžeme individuálně navýšit.

HTTP REST API vs. WAPI

WEDOS nabízí dvě API: starší WAPI a novější HTTP REST API v2. Porovnat je můžete pomocí následující tabulky:

	WAPI	HTTP REST API v2
Autentizace	Jedno přihlašovací jméno a WAPI heslo pro celý účet	Samostatný API klient s vlastním tokenem pro každou aplikaci nebo osobu
Omezení přístupu	Povinný seznam IP adres pro celý účet	Oprávnění (scopes), „Pouze pro čtení“, IP adresy a platnost tokenu, nastavené pro každého klienta zvlášť
Formát	XML nebo JSON, jediný endpoint, příkazy v těle požadavku	REST (HTTP metody a URL), JSON
Pokrytí	Široká škála příkazů pro služby WEDOS	domény, kontakty, NSSETy, WEDOS DNS, WEDOS Global Protection
Log	Jeden log pro celý účet	Log, který identifikuje API klienta

Doporučujeme používat:

• HTTP REST API v2 pro nové integrace, pokud pokrývá operace, které potřebujete, a všude tam, kde potřebujete oddělit přístup jednotlivých osob nebo systémů, omezit je pouze na čtení nebo dohledat, kdo co udělal (audit, DORA).
• WAPI pro operace, které HTTP REST API v2 zatím nenabízí.

Pokud chcete přejít z WAPI na WEDOS REST API, postupujte takto:

1. V administraci vytvořte pro každou aplikaci nebo systém API klienta s potřebnými oprávněními (scopes). Návod najdete v kapitole Správa klientů .
2. Nahraďte volání příkazů WAPI odpovídajícími endpointy z dokumentace jednotlivých API. Viz kapitolu Endpointy .
3. Kódy výsledku operace (například 1000 OK, 3201 doména je již zaregistrována) jsou stejné jako ve WAPI, protože HTTP REST API v2 provádí tytéž operace. Navíc existují obecné kódy REST vrstvy (například 2000 chybějící nebo neplatný token, 2012 klient pouze pro čtení), popsané v dokumentaci jednotlivých API.
4. Během přechodu můžete obě API používat současně.

---

Endpointy

WEDOS REST API umožňuje automatizovat správu těchto oblastí:

• Domény: Endpointy /domains/ zajišťují registraci, přeregistrace a prodloužení domén. Umí také odesílat AUTH-ID a nastavovat DNS servery/NSSET a KEYSET pro DNSSEC. Jejich oprávnění (scope) je domény. Více informací najdete v článku REST API – Domény .
• Kontakty domén: Endpointy /contacts/ vytvářejí a spravují kontakty domén. Pro domény .cz jsou k dispozici přeregistrace. Jejich oprávnění (scope) je domény. Více informací najdete v článku REST API – Kontakty domén .
• NSSETy: Endpointy /nssets/ vytvářejí a spravují objekty NSSET sdružení CZ.NIC. Jejich oprávnění (scope) je domény. Více informací najdete v článku REST API – NSSETy domén .
• DNS: Endpoint /dns/ vytváří a spravuje DNS domény i jednotlivé záznamy. Zahrnuje to importy do primárního DNS a AXFR pro sekundární DNS. Jeho oprávnění (scope) je dns. Více informací najdete v článku REST API – DNS .
• WEDOS.protection: Endpoint /wgp/ endpointy vytvářejí a spravují služby WEDOS.protection. Jejich oprávnění (scope) je wgp. Více informací najdete v článcích REST API – WGP Domains, REST API – WGP Services a REST API – WGP Members.

---

Správa klientů

Přístup k API nastavíte v zákaznické administraci v sekci HTTP REST API . Pro každou aplikaci, systém nebo osobu vytvořte samostatného API klienta . U každého klienta nastavíte:

• Oprávnění (scopes): ke kterým API má klient přístup,
• Pouze pro čtení: klient může informace pouze zobrazovat (viz níže),
• Filtrování IP adres: povolené nebo blokované IP adresy, ze kterých klient může API volat,
• Platnost tokenu: kdy začne access token platit a kdy vyprší.

Klient se autentizuje access tokenem v hlavičce Authorization: Bearer <TOKEN> . Token můžete vygenerovat přímo v administraci, nebo si jej vaše aplikace může vyžádat sama pomocí client ID a client secret (viz kapitolu OAuth2 ).

Vytvoření nového klienta

Nového klienta lze vytvořit pouze v zákaznické administraci. Postupujte takto:

1. Přihlaste se do zákaznické administrace.
2. Přejděte do rozhraní WEDOS REST API (aktuálně nedostupné).
3. Klikněte na tlačítko Nový klient .
4. Zadejte Název klienta (krátký název, který klienta identifikuje v seznamu) a vyberte jednu nebo více oblastí oprávnění z nabídky Vybrat oprávnění . Dostupné oblasti odpovídají endpointům.
5. Volitelně proveďte další nastavení:
   • Zaškrtněte přístup Pouze pro čtení . Klient pak může informace pouze vyžadovat. Požadavky, které položky přidávají, upravují nebo mažou, jsou blokovány.
   • V části Platnost tokenuzvolte, jak dlouho token zůstane platný po svém vydání: Bez expirace, 7 dní, 30 dní, 90 dní, 1 rok nebo Vlastní. Pole Platné od a Expirace zobrazují výsledná data.
   • V části Bezpečnostní omezenímůžete volitelně zapnout Filtrování IP adres a zadat povolenou IP adresu. Pro další adresy klikněte na + Přidat další , nebo na × pro odebrání adresy. Je-li filtrování zapnuté, API přijímá požadavky pouze z uvedených adres.

Po dokončení nastavení jej potvrďte tlačítkem Vytvořit klienta .

Nový klient se objeví v seznamu se svým názvem, oprávněními, typem přístupu (například read, write), daty platnosti a stavem. Seznam můžete filtrovat podle těchto položek: Oprávnění, Stav, Platnost a Přístup.

Client Secret

Ihned po vytvoření klienta se zobrazí dialog Tajný klíč klienta se zprávou Zkopírujte tajný klíč a uložte jej na bezpečné místo.

1. Klikněte na Kopírovat vedle tajného klíče.
2. Uložte tajný klíč na bezpečné místo, například do správce hesel nebo do úložiště tajných údajů na vašem serveru.
3. Klikněte na Rozumím, zavřít.

Tajný klíč se zobrazí pouze v tomto dialogu, proto jej uložte dříve, než dialog zavřete. Spolu s client ID jej potřebujete k vyžádání tokenů přes API (viz kapitolu OAuth2).

Správa existujícího klienta

Stránku Nastavení HTTP REST API klienta otevřete kliknutím na ikonu úprav vedle jeho názvu v seznamu. Můžete upravit libovolné nastavení zadané při vytváření, včetně názvu a oprávnění.

Client ID a Client Secret upravit nelze.

Při správě existujícího klienta jsou k dispozici tyto ovládací prvky:

• Uložit změny: Uloží změny v nastavení klienta.
• Zakázat: Deaktivuje (zablokuje) klienta bez jeho smazání.
• Smazat: Trvale klienta odstraní.
• Zpět na seznam HTTP REST API: Návrat na seznam klientů.
• Obnovit: Znovu načte stránku.

Bearer token klienta

Pole Bearer token slouží k identifikaci klienta při přístupu k endpointům. Zobrazuje aktuální access token klienta. Kliknutím na Kopírovat jej zkopírujete.

Token nahradíte kliknutím na Nový token. Starý token okamžitě přestane fungovat, proto aktualizujte všechny aplikace, které jej používají.

Sekce Příklad (curl) zobrazuje připravený požadavek s aktuálním tokenem pro testovací účely.

OAuth2

Vaše aplikace si může vyžádat vlastní token na POST https://api.wedos.com/oauth2/token pomocí client ID a tajného klíče. Jakákoli jiná HTTP metoda vrátí chybu.

• Client ID: V rozhraní pro správu klientůklikněte na Zobrazit Client ID , čímž client ID zobrazíte, a poté klikněte na Kopírovat.
• Client Secret: Tajný klíč je dostupný pouze po vytvoření účtu. Více informací najdete v kapitole Client Secret .

Použijte jednu ze dvou metod:

• HTTP Basic (doporučeno): hlavička Authorization: Basic <base64(client_id:client_secret)>. curl ji za vás sestaví pomocí -u 'client_id:client_secret'.
• V těle požadavku: parametry client_id a client_secret.

Parametry odesílejte v těle jako application/x-www-form-urlencoded, nebo jako JSON s hlavičkou Content-Type: application/json.

Parametr	Povinný	Popis
grant_type	Ano	Vždy client_credentials
scope	Ne	Oprávnění (scopes) oddělená mezerou z těchto možností: domains (zahrnuje kontakty domén a NSSET), wdns a wgp. Musí jít o podmnožinu scopes klienta. Pokud je parametr vynechán, token získá všechny scopes klienta.
client_id, client_secret	Pouze bez HTTP Basic	Přihlašovací údaje klienta

Příklad: HTTP Basic (doporučeno)

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

Příklad: Přihlašovací údaje v těle požadavku

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'

Pří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 při vydání tokenu, nebo 2000 při chybě autentizace klienta či neplatném požadavku.

Při úspěchu data obsahují:

Pole	Popis
access_token	Token, odesílaný jako Authorization: Bearer <TOKEN>
token_type	Typ tokenu (Bearer)
expires_in	Platnost v sekundách (výchozí 3600, tj. 1 hodina)
scope	Scopes, které token skutečně získal

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

Refresh token se pro client_credentialsnevydává. Po vypršení platnosti tokenu si vyžádejte nový stejným voláním.

Při chybě data obsahují status_code (HTTP status OAuth2, např. 400 nebo 401), error a error_description.

error	Příčina
invalid_client	Neplatný client_id nebo client_secret, nebo je klient zablokovaný
invalid_request	grant_type nebo jiná povinná hodnota chybí, případně metoda nebyla POST
unsupported_grant_type	Nepodporovaná hodnota parametru grant_type .
invalid_scope	Požadovaný scope neexistuje nebo není klientovi přiřazen

{
  "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 odesílejte v hlavičce Authorization při volání libovolného endpointu v2, který spadá do scope tokenu.

Příklad:

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

Snažte se dodržovat tyto doporučené postupy:

• Token si uložte a používejte jej opakovaně, dokud nevyprší jeho platnost (expires_in). Nežádejte o nový token před každým voláním API.
• Pokud endpoint v2 vrátí chybu autentizace (2000), vyžádejte si nový token a volání zopakujte.
• Žádejte pouze o scopes, které vaše aplikace potřebuje, a použijte Pouze pro čtení u klientů, kteří nikdy nemění data.
• Kde je to možné, omezte každého klienta na známé IP adresy.
• Pro každou aplikaci vytvořte samostatného klienta, abyste mohli jednoho zakázat nebo smazat bez vlivu na ostatní.

Doporučené nastavení pro týmy

Pokud má k API přístup více osob, doporučujeme toto nastavení:

• Jeden API klient na osobu nebo systém. Z logu je patrné, kdo který požadavek provedl, a když někdo odejde, zablokujete pouze jeho klienta.
• Pouze potřebné scopes. Klient pro DNS nepotřebuje přístup k doménám.
• „Pouze pro čtení“, kdekoli to stačí – monitoring, reporty, kontroly stavu.
• Omezení na IP adresy serverů nebo sítí, které API skutečně volají.
• Expirace tokenu. Nastavte dobu platnosti a token pravidelně obnovujte.
• Tajný klíč klienta uchovávejte pouze na straně serveru – nikdy ne v prohlížeči, v mobilní aplikaci ani ve veřejném repozitáři.

Když někdo odejde:

1. Zablokujte nebo smažte jeho API klienta v seznamu klientů. Všechny jeho tokeny okamžitě přestanou fungovat a nový token pro něj nelze vyžádat. Ostatních klientů se to nedotkne.
2. Pokud jeho práci přebírá někdo jiný, vždy vytvořte nového klienta pro tuto osobu.

---

Logování požadavků

Sekce HTTP REST API v administraci obsahuje log požadavků. Můžete jej filtrovat podle oprávnění (scope), API klienta, stavu a HTTP metody.

Pro přístup k logu postupujte takto:

1. Přihlaste se do zákaznické administrace.
2. Přejděte do rozhraní WEDOS REST API (aktuálně nedostupné).
3. Klikněte na tlačítko Zobrazit log požadavků HTTP REST API .

Každý klient v seznamu má navíc odkaz log , který otevře log filtrovaný na požadavky tohoto klienta.

U každého požadavku zaznamenáváme:

• datum a čas a IP adresu, ze které požadavek přišel,
• API klienta (ID a název) a oprávnění (scope),
• HTTP metodu, URL a provedený příkaz,
• vstupní data a odpověď API (výsledek a návratový kód).

Nezaznamenáváme:

• access token ani tajný klíč klienta – hlavička Authorization se v logu požadavků neukládá a token je v interních záznamech WEDOS maskovaný,
• citlivé hodnoty ve vstupních datech (hesla a podobně) se ukládají maskované.

Další důležité informace:

• Vstupní data a odpověď se ukládají dohromady do 1 024 znaků. Delší obsah je zkrácen.
• Záznamy se uchovávají 90 dní, poté jsou automaticky smazány.
• Log zatím nelze exportovat ani číst přes API. Je dostupný pouze v zákaznické administraci.

---

Často kladené otázky