Doménové API

API registrace domén

API (Application Programming Interface) je určen pro vzdálený – strojový přístup k rozhraní pro správu doménových jmen. Rozhraní je zpřístupněno pomocí protokolu SOAP (Simple Object Access Protocol), který má podporu ve většině běžně používaných jazyků.

• Seznam metod
• Historie
• Jak získat přístup k API
• Pravidla použití
• Limity přístupů
• Příklad volání z PHP5
• Příklad zpracování chyb
• Tabulka chybových hlášení

Historie

Verze 2.0 (26. 10. 2010)

• Nové rozhraní.
• Nová dokumentace.

Verze 1.3 (16.02.2009)

• Přidání funkcí pro zaslání transfer hesel.
• Úprava dokumentace.

Verze 1.2 (9.10.2008)

• Úprava dokumentace (chybové kódy).
• Přidání COCZ funkcí.

Verze 1.1 (22.04.2008)

• Přidána captcha k infoslužbám pro cizí .CZ domény.
• Přidány info služby (vlastní domény bez captcha).

Verze 1.0 (15.04.2008)

• Zveřejnění API.

Jak získat přístup k API

Pro přístup k doménovému API stačí mít přístup k ovládacímu panelu se službou „Správa Domén“. Pokud účet nemáte stačí jej zaregistrovat. Po úspěšné registraci máte zřízeny jak doménové služby v ovládacím panelu tak i SOAP přístup, který můžete ihned využívat dle níže uvedené dokumentace.

Pravidla použití

Pravidla použití se řídí především Smluvními dokumenty.

Uživatel je dále oprávněn službu užívat pouze v případě, že:

• užití není v rozporu s dobrými mravy a právy třetích osob,
• uživatel nezneužívá službu pro strojové čtení dat službou poskytnuté,
• uživatel nezneužije rozhraní k poškození poskytovatele.

Limity přístupů

Služba má interně nastavené bezpečnostní limity pro volání.

Omezení dle IP adresy

API dokáže přijímat rychlostí cca 3 požadavky za sekundu. Pokud je k API přistupováno z více vláken je nutné dodržet limit 3 požadavky za sekundu. V případě nedodžení stanoveného limitu systém vrací vyjimky. Pokud však přistupujete z jednoho vlánka (aplikace) stačí rozhraní běžně používat a k vrácení výjimky nedojde.

Omezení na počty volání jednotlivých funkcí:

Pokud bude volána jakákoliv stejná funkce dříve jak 3 sec od předchozího volání bude o 3 sec pozdržena (první volání je bez zdržení). V případě volání vícevláknově (několik spojení zároveň) je při nedodžení odstupu 3 sec vyvolána výjimka.

V praxi limity fungují následovně:

// Bez omezení
domainContactCreate();
domainNSSetCreate();
domainCreate();

// Druhé volání opožděno o 3 vteřiny.
comainContactCreate();
domainContactCreate();

Příklad volání z PHP5

Základní předpoklady:

• je vyžadována verze PHP5,
• všechny vstupy a výstupy jsou v UTF8,
• adresa WSDL je http://www.web4u.cz/cp/wsdl/Web4uGateway.wsdl
• každé volání má první tři parametry obdobné – přihlašovací jméno, heslo, identifikátor služby, za nimi následuje object s nastavenými parametry volání.

Ověření funkčnosti SOAP volání

Zda vše funguje jak má lze ověřit následujícím způsobem:

$client = new SoapClient("http://www.web4u.cz/cp/wsdl/Web4uGateway.wsdl");
echo $client->greeting();

Volání vypíše: Greeting from Web4u soap gateway

Jak získat identifikátor služby:

Identifikátor služby (Správy Domén), pod kterou budete funkce volat, získáte jakýmkoliv zavoláním existující funkce, pouze s vašimi parametry „login“, „password“. Výsledkem bude výjimka obsahující přehled použitelných služeb s jejich ID.

try{
	$client = new SoapClient("http://www.web4u.cz/cp/wsdl/Web4uGateway.wsdl", $options);
	$result = $client->domainCheck("login", "password");
}catch(Exception $e){
	var_dump($e->getMessage());
}

Přehled služeb můžete získat také voláním funkce getServiceList s parametry „login“, „password“.

Příklad volání

try{
	$options = array(
		"cache_wsdl" => WSDL_CACHE_NONE,
		"features"   => SOAP_SINGLE_ELEMENT_ARRAYS
	);
	$client = new SoapClient("http://www.web4u.cz/cp/wsdl/Web4uGateway.wsdl", $options);
	$params = array(array(
		"name" => "domain_name", // Název attributu
		"data" => "test.cz" // Hodnota attributu
	));
	$result = $client->domainCheck(
		"login", "password", "id_service", $params
	);
}catch(SoapFault $e){
	// Zpracování soap výjimky
}catch(Exception $e){
	// Zpracování ostatních výjimek
}
var_dump($result);

První parametry lze pak skrýt následovně:

class Web4uSoapClient extends SoapClient{
	static private
		$options = array(
			"cache_wsdl" => WSDL_CACHE_NONE,
			"features"   => SOAP_SINGLE_ELEMENT_ARRAYS
		),
		$url = "http://www.web4u.cz/cp/wsdl/Web4uGateway.wsdl",
		$login = "muj_login",
		$pwd = "moje_heslo",
		$srv = "moje_service_id"
	;

	public function __construct(){
		parent::__construct(self::$url, self::$options);
	}

	public function __call($method, $args){
		return parent::__call($method, array(
			self::$login, self::$pwd, self::$srv, $args[0]
		));
	}
}

pak voláme:

...
$client = new Web4uSoapClient();
$result = $client->domainCheck(array(array(
	"name" => "domain_name", "data" > "test.cz"
)));
print_r($result);
...

Příklad zpracování chyb

try{
	$client = new Web4uSoapClient();
	$result = $client->domainCheck(array(array(
		"name" => "domain_name", "data" => "test.cz"
	)));
}catch(SoapFault $e){ // Zpracování soap výjimky
	// Validační chyby
	if($e->faultcode == 10){
		$lines = explode("\n", $e->faultstring);
		foreach($lines as $line){ // Získané hodnoty z validátoru
			list($ecode, $emesg, $eexam, $ehelp, $eval) = explode('|',$line);
			print_r($emesg);
		}
	}else{ // Ostatní zpracování
		print_r($e->faultstring);
	}
}catch(Exception $e){ // Zpracování ostatních výjimek
	print_r($e->getMessage());
}
print_r($result);

Tabulka chybových hlášení

Chyby které jsou vraceny přímo (s chybovým kódem):

Následující chyby jsou „zabaleny“ v chybě číslo 10 (chyba validace), pokud mají číslo jedná se o níže definované chyby, jinak se jedná o chyby validačního charakteru.