API Váš Hosting: dokumentace a vygenerování klíče

API (Application Programming Interface) je způsob, kterým spolu mohou komunikovat dva programy – vaše aplikace nebo skript pošle našemu systému požadavek a ten ho automaticky vykoná a vrátí odpověď. Díky tomu můžete správu serverů, domén i zákaznického účtu automatizovat: místo ručního proklikávání v rozhraní napíšete skript nebo si postavíte vlastní administraci třeba pro své klienty. Váš Hosting nabízí tři samostatná API: jedno pro Zákaznický portál a dvě pro VPS Centrum, zvlášť pro novější verzi V3 a starší V2.

Tento článek je rozcestník. Najdete v něm odkazy na všechny dostupné API dokumentace na jednom místě, stručné vysvětlení, jak API funguje a jak se ověřuje, a návod, jak si v každém rozhraní vygenerovat vlastní API klíč.

Rychlý přehled pro pokročilé

Všechna API Váš Hosting používají architekturu REST a komunikují přes HTTPS. Ověřování probíhá pomocí API klíče, který přikládáte v hlavičce požadavku a který si vygenerujete v příslušném rozhraní.

Rozhraní	Kde vygenerovat klíč	Dokumentace
Zákaznický portál	Účet a kontakty → API klíče → + Nový API klíč	Postman
VPS Centrum V3	VPS Centrum → API Klíče → + Vytvořit API klíč	Postman
VPS Centrum V2	VPS Centrum → Správa server → řádek API klíč → Vygenerovat	Apiary

Které API zvolit: na VPS spravujete server a vše na něm (domény, PHP, databáze, e-maily) přes API VPS Centra. Účet, fakturaci, objednávky, domény na úrovni účtu – a celý webhosting, který VPS Centrum nemá – spravujete přes API Zákaznického portálu.

K čemu API využijete

Konkrétní možnosti závisí na tom, ke které službě dané API patří. Můžete například:

• automatizovat vytváření a správu domén,
• programově spravovat e-mailové schránky,
• vytvářet vlastní administrační rozhraní pro klienty,
• napojit hostingové služby na vlastní workflow,
• provádět hromadné operace bez ručního proklikávání.

Typický příklad: spravujete desítky domén a u všech potřebujete založit stejnou e-mailovou schránku. Ručně byste museli proklikat každou doménu zvlášť – krátký skript to přes API zvládne hromadně podle seznamu během chvíle.

Co je dobré vědět předem

Než si klíč vygenerujete, mějte na paměti jednu zásadní věc: API klíč má stejná oprávnění jako váš účet. Kdokoli, kdo ho získá, může přes API spravovat všechny vaše služby – domény, e-maily, databáze i nastavení serveru – stejně, jako byste to dělali vy sami. Zacházejte s ním proto se stejnou opatrností jako s heslem: nikomu ho nesdělujte, nezveřejňujte ho a při jakémkoli podezření, že se dostal do nesprávných rukou, ho v rozhraní zrušte a vygenerujte si nový.

Co budete potřebovat

• Aktivní službu (povinné) – pro API VPS Centra běžící VPS, pro API Zákaznického portálu zákaznický účet u Váš Hosting. Klíč si pak sami vygenerujete v příslušném rozhraní – ve VPS Centru, nebo v Zákaznickém portálu.
• HTTP klient nebo knihovnu (doporučené) – nástroj, kterým budete požadavky odesílat. Pro rychlé vyzkoušení stačí curl (nástroj příkazové řádky, na macOS i Linuxu předinstalovaný – spustíte ho v Terminálu) nebo grafický Postman. Do vlastní aplikace pak knihovna ve vašem programovacím jazyce.

Časový odhad: Vygenerování klíče zabere pár minut. Doba samotné integrace závisí na tom, co a jak složitě chcete automatizovat.

Jak zjistíte, jakou verzi VPS Centra máte

Verze VPS Centra se zobrazuje přímo v rozhraní – ve VPS Centru V3 v pravém dolním rohu, ve VPS Centru V2 v patičce. Pokud číslo začíná trojkou, používáte V3, pokud dvojkou, V2. V tomto článku je rozdíl podstatný: cesta k vygenerování API klíče je v každé verzi jiná.

Skok rovnou k postupu

Pokud víte, co API klíč je, a chcete ho rovnou vygenerovat, přejděte na API klíč a jeho vygenerování.

Jak funguje autentizace API

Základní princip je u všech tří API stejný:

• REST je rozšířený způsob, jak spolu aplikace komunikují přes web. Požadavky posíláte na konkrétní adresy běžnými HTTP metodami – GET pro čtení dat, POST pro vytvoření, PUT nebo PATCH pro úpravu, DELETE pro smazání.
• Endpoint je konkrétní adresa, na kterou požadavek voláte – například pro výpis domén nebo založení schránky. Seznam všech endpointů i s příklady najdete v dokumentaci příslušného API.
• HTTPS zajišťuje, že je přenos mezi vaší aplikací a serverem šifrovaný.

Aby server poznal, že požadavek opravdu patří vám, přikládáte API klíč do hlavičky požadavku:

• API Zákaznického portálu a API VPS Centra V3 používají hlavičku X-API-Key.
• API VPS Centra V2 používá dvě hlavičky: x-vpsc-admin s e-mailem administrátora VPS Centra a x-vpsc-apikey s API klíčem.

Přesné názvy hlaviček i další detaily najdete vždy v dokumentaci daného API.

API klíč a jeho vygenerování

API klíč je jedinečný řetězec znaků, kterým se vaše aplikace při volání API prokazuje – něco jako heslo, jen pro programy místo lidí. Vygenerujete si ho sami přímo v rozhraní. Postup se liší podle toho, kterou službu chcete přes API spravovat – vyberte si níže.

Vygenerování klíče – Zákaznický portál

Klíč pro API Zákaznického portálu (správa účtu, fakturace, objednávek a domén) vygenerujete v sekci Účet a kontakty.

1. Přihlaste se do Zákaznického portálu a v levém panelu klikněte na Účet a kontakty.
2. Otevřete podsekci API klíče.
3. Klikněte na + Nový API klíč.
4. Vyplňte Poznámku (název, podle kterého klíč poznáte) – je povinná. Volitelně nastavte expiraci. Potvrďte tlačítkem Vytvořit.
5. Klíč se zobrazí jen jednou – zkopírujte si ho a bezpečně uložte.

Klíč se objeví v seznamu. Na konci jeho řádku je tlačítko se třemi tečkami …, přes které ho přegenerujete nebo smažete.

Vygenerování klíče – VPS Centrum V3

Klíč pro API VPS Centra V3 (správa serveru, domén, PHP, databází a dalších služeb) vygenerujete v sekci VPS Centrum.

1. Ve VPS Centru klikněte v levém panelu na VPS Centrum.
2. Otevřete podsekci API Klíče.
3. Klikněte na + Vytvořit API klíč.
4. Ve formuláři vyplňte Poznámku (název, podle kterého klíč poznáte) – ta je povinná. Volitelně nastavte expiraci a Povolené IP adresy (jednu na řádek; prázdné pole znamená přístup odkudkoli). Potvrďte tlačítkem Vytvořit API klíč.
5. Klíč se zobrazí jen jednou – zkopírujte si ho a bezpečně uložte.

Klíč se objeví v seznamu. Na konci jeho řádku je tlačítko se třemi tečkami …, přes které ho kdykoli upravíte nebo smažete.

Vygenerování klíče – VPS Centrum V2

Ve VPS Centru V2 najdete generování klíče ve Správě serveru.

1. Ve VPS Centru V2 klikněte v horním menu na Správa serveru.
2. U řádku API klíč klikněte na Vygenerovat.
3. Vygenerovaný klíč si zkopírujte a bezpečně uložte.

Hned pod řádkem API klíč je pole Povolené IP adresy pro API se stejnou funkcí jako ve VPS Centru V3 – když ho vyplníte, půjde klíč použít jen z uvedených adres.

Příklad volání API – webhosting a V3

Po vygenerování klíče se hodí jedním požadavkem ověřit, že funguje. Příklad níže vypíše seznam databází na konkrétní doméně – jen čte, takže nic nezmění ani nerozbije. Na webhostingu (přes API Zákaznického portálu) i ve VPS Centru V3 (přes API VPS Centra V3) voláte úplně stejně: stejná hlavička X-API-Key, stejné endpointy i stejná odpověď. Liší se jen adresa, na kterou požadavek míří:

• webhosting: https://portal.vas-hosting.cz/api/v1/ – pevná, stejná pro všechny
• VPS Centrum V3: https://HOSTNAME.vas-server.cz/vpsc/api/v1/ – kde HOSTNAME je hostname vašeho serveru

Z terminálu volání otestujete nástrojem curl, který je dnes předinstalovaný na macOS, Linuxu i Windows (verze 10 a 11) – nic nestahujete.

Tady je stejný požadavek pro obě prostředí:

Webhosting (přes API Zákaznického portálu):

curl --location 'https://portal.vas-hosting.cz/api/v1/domains/DOMENA/databases' \
  --header 'X-API-Key: VAS_API_KLIC'

VPS Centrum V3 (adresa vašeho serveru):

curl --location 'https://HOSTNAME.vas-server.cz/vpsc/api/v1/domains/DOMENA/databases' \
  --header 'X-API-Key: VAS_API_KLIC'

Nahraďte DOMENA doménou, jejíž databáze chcete vypsat, a VAS_API_KLIC svým API klíčem; u VPS Centra V3 navíc HOSTNAME hostnamem svého serveru. Endpoint, hlavička i metoda jsou v obou stejné.

Druhou možností je zavolat API přímo z PHP pomocí knihovny cURL – tak, jak by takové volání probíhalo uvnitř vaší aplikace. Vyzkoušet si ho můžete i ručně přímo na VPS.

Přihlaste se k serveru přes SSH (zabezpečené vzdálené připojení k příkazové řádce serveru). V domovské složce vytvořte nový soubor příkazem nano test.php – otevře se jednoduchý textový editor nano přímo v okně terminálu. Soubor záměrně zakládáte v domovské složce, mimo webový prostor s vašimi weby: kdyby ležel tam a server ho z nějakého důvodu nevykonal, mohl by se API klíč uvnitř zobrazit komukoli z internetu.

Do editoru vložte následující skript. Míří na adresu API VPS Centra V3 – nahraďte v něm HOSTNAME hostnamem svého serveru:

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://HOSTNAME.vas-server.cz/vpsc/api/v1/domains/DOMENA/databases',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'X-API-Key: VAS_API_KLIC'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Dále nahraďte DOMENA doménou, jejíž databáze chcete vypsat, a do hlavičky X-API-Key doplňte svůj API klíč – ten si do ukázky musíte přidat sami, Postman ho do vygenerovaného kódu nepromítne. Soubor pak uložte klávesami Ctrl+O a potvrďte Enter, editor zavřete Ctrl+X. Skript spustíte příkazem php test.php – vypíše odpověď serveru, kterou vidíte níže. Až si volání ověříte, soubor smažte příkazem rm test.php, ať na serveru nezůstává otevřený soubor s API klíčem.

Na webhostingu se stejné volání liší ve dvou věcech. Míří na pevnou adresu API Zákaznického portálu(místo adresy serveru), takže v kódu výše byste nahradili řádek https://HOSTNAME.vas-server.cz/vpsc/api/v1/domains/DOMENA/databases pevným řádkem https://portal.vas-hosting.cz/api/v1/domains/DOMENA/databases. A protože webhosting přístup přes SSH nemá, skript na něm nespustíte přímo na serveru jako na VPS. Pokud si chcete jen ověřit, že klíč i volání fungují, nemusíte kvůli tomu nic programovat ani instalovat: curl příkaz s webhostingovou adresou (ukázaný na začátku této sekce) spustíte rovnou z terminálu svého počítače – curl je na macOS, Linuxu i Windows předinstalovaný a nepotřebujete k němu žádný účet. Samotný PHP skript pak spustíte buď lokálně na svém počítači (pokud na něm máte PHP), nebo ho rovnou zapojíte do aplikace běžící na webhostingu.

Pokud klíč funguje, vrátí se vám seznam databází na doméně ve formátu JSON:

{
    "mojeweb_db": {
        "user": "mojeweb.1234",
        "type": "mysql",
        "size": 100
    },
    "eshop_pg": {
        "user": "eshop_1234",
        "type": "postgresql",
        "size": 300
    }
}

U každé databáze vidíte přihlašovací jméno (user), typ (type – mysql, nebo postgresql) a velikost (size). Tím máte ověřeno, že klíč i spojení fungují, a můžete přejít k dalším endpointům z dokumentace. Pokud místo výpisu dostanete chybu 401 Unauthorized, klíč se neodeslal správně – podívejte se na Volání API vrací chybu 401 Unauthorized.

A co VPS Centrum V2? Pro V2 příklad záměrně neuvádíme. Je to starší rozhraní, do kterého už nepřibývají nové funkce, a jeho API dokumentace běží na platformě Apiary, kterou její provozovatel postupně ukončuje. Princip volání je přitom stejný jako u webhostingu a V3 – liší se jen přihlašovací hlavičky (viz Jak funguje autentizace API) a endpointy najdete v dokumentaci API VPS Centra V2. Pokud na V2 ještě běžíte, doporučujeme přejít na aktuální V3.

Dostupné API dokumentace

Každé API má vlastní dokumentaci s popisem všech endpointů, příklady volání a možností požadavky rovnou otestovat. Odkazy jsou seřazené stejně jako zbytek článku: Zákaznický portál, VPS Centrum V3, VPS Centrum V2.

Dokumentace API Zákaznického portálu

API pro správu zákaznického účtu, fakturace a objednávek. Umožňuje například automatické objednávání služeb nebo správu kontaktů. Dokumentace je na platformě Postman – dostanete se k ní i přímo z portálu přes Podpora → API dokumentace nebo Účet a kontakty → API klíče → API dokumentace.

Dokumentace: documenter.getpostman.com – API Zákaznického portálu

Dokumentace API VPS Centra V3

Aktuální verze API pro správu VPS serverů s rozšířenými možnostmi. Dokumentace je na platformě Postman – dostanete se k ní i přímo z VPS Centra: v sekci API Klíče rozbalte nápovědu ikonou ? a klikněte na Dokumentace.

Dokumentace: documenter.getpostman.com – API VPS Centra V3

Dokumentace API VPS Centra V2

Starší verze API pro správu serverů přes VPS Centrum V2. Dokumentace je na platformě Apiary a obsahuje kompletní popis všech endpointů včetně možnosti testování. Dostanete se k ní i přímo z rozhraní – ve Správě serveru je u pole API klíč odkaz Dokumentace.

Dokumentace: vpscentrum.docs.apiary.io

Řešení problémů

Volání API vrací chybu 401 Unauthorized

Symptom: Server na požadavek odpoví stavovým kódem 401 Unauthorized.

Příčina: Chybná autentizace – nesprávný nebo zrušený klíč, případně chybějící nebo špatně pojmenovaná hlavička s klíčem.

Řešení: Zkontrolujte, že posíláte klíč ve správné hlavičce. Hlavičky se mezi API liší: API Zákaznického portálu a API VPS Centra V3 očekávají X-API-Key, API VPS Centra V2 dvojici x-vpsc-admin a x-vpsc-apikey. Pokud klíč nefunguje, vygenerujte nový. U VPS Centra V2 a V3 navíc zkontrolujte pole Povolené IP adresy pro API – je-li vyplněné, musíte volat z některé z uvedených adres.

V rozhraní nevidím sekci API klíče

Symptom: Nemůžete najít, kde se klíč generuje.

Příčina: Hledáte v jiném rozhraní, než kam dané API patří, nebo přihlášený účet nemá dostatečná oprávnění.

Řešení: Klíč pro VPS je ve VPS Centru (V3 v sekci VPS Centrum, V2 ve Správě serveru). Klíč pro účet a objednávky je v Zákaznickém portálu v sekci Účet a kontakty. Pokud sekci nevidíte ani na správném místě, přihlášený účet nemá potřebná oprávnění – přihlaste se hlavním účtem, nebo o vygenerování požádejte jeho správce.

Nevím, které API mám pro svůj úkol použít

Symptom: Tři API a není jasné, které zvolit.

Příčina: Funkce se částečně překrývají, hlavně u domén.

Řešení: Rozhodující je úroveň, na které pracujete, ne kde věc vidíte. Operace s konkrétním serverem jdou přes API VPS Centra (V3, nebo V2 podle verze rozhraní), operace s vaším účtem – objednávky, fakturace, kontakty – přes API Zákaznického portálu. U domén záleží na tom, co s nimi děláte: registraci, převod a další úkony na úrovni účtu řeší Zákaznický portál, kdežto nastavení domény na konkrétním VPS (webserver, PHP, databáze) řeší VPS Centrum.

Potřebuji nový klíč nebo jsem ten starý ztratil

Symptom: Klíč nemáte uložený nebo ho potřebujete vyměnit.

Příčina: V Zákaznickém portálu a ve VPS Centru V3 se klíč zobrazí jen jednou a rozhraní ho později znovu neukáže – uložit si ho musíte hned. Ve VPS Centru V2 zůstává klíč viditelný v nastavení serveru.

Řešení: Vygenerujte nový klíč stejným postupem jako poprvé a ten starý zneplatněte, ať ho nikdo nezneužije. V Zákaznickém portálu klikněte u klíče na tlačítko se třemi tečkami … a zvolte Přegenerovat (vytvoří nový klíč k téže poznámce), nebo Smazání. Ve VPS Centru V3 klikněte u klíče na tlačítko se třemi tečkami … a zvolte Smazat. Ve VPS Centru V2 použijte u pole API klíč tlačítko Zrušit – protože V2 pracuje s jediným klíčem, vygenerování nového ten původní rovnou nahradí.

Pokud problém přetrvává, kontaktujte naši podporu. Rádi pomůžeme.