Aus EUserv Wiki

Version vom 12:06, 31. Aug. 2012 bei Root (Diskussion | Beiträge)

(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)

Wechseln zu: Navigation, Suche

Languages:

Deutsch • English

Inhaltsverzeichnis

1 EUserv Reseller API
- 1.1 Introduction
- 1.2 History of Changes
2 Method Specifications

EUserv Reseller API

Introduction

Technology

Our API is based on the XML-RPC protocol, which is a Remote Procedure Calling protocol that works over the Internet.

XML-RPC messages are HTTP-POST requests in XML (Extensible Markup Language).

A “method call” will be executed on the server and will produce a response, which is also formatted in XML and which can be decoded into several variables.
Method call parameters and returned variables can be strings, integers (numbers) and also complex types like arrays and hashes. Required parameters and return values are method-specific. Some parameters or return values are marked as “optional”; all other values/parameters are required.

API Servers

Please note that both servers currently use self-signed SSL certificates! It is possible, that you have to disable “peer verifying” to connect!

The live environment is available over HTTPS (HTTP over SSL, Port 443) at:
– https://api.euserv.net:443
For developing/testing purposes, please use the sandbox environment, which is also available over HTTPS(Port 443) at:
– https://api.test.euserv.net:443

The sandbox environment is a virtual environment for testing and developing. All data/values/servers/orders will be copied into the sandbox environment every night, excepting the API user accounts. That means you have to create separate API user accounts within the sandbox environment. Assigned tasks, e.g. server resets or reinstallations, will automatically marked as done every 5 minutes.

PHP Examples

We have added PHP examples to show you, how you can use our API with PHP. In our examples, we use 'XML-RPC for PHP' as the core libary. You can find this libary here:
http://phpxmlrpc.sourceforge.net/.

History of Changes
Version	Changes
0.5.1	- Add method 'server.ipaddr_get_reverse' - Add method 'server.get_possible_server_items' - Add method 'server.order_server'
0.5.2	- Update method 'server.get_possible_server_items' - Update method 'server.order_server'
0.5.3	- Add method 'domain.get_domain_orders' - Add method'domain.get_domain_order_details' - Add method 'domain.dns_create_record' - Add method 'domain.dns_delete_record' - Add method 'domain.dns_update_record' - Add method 'domain.dns_get_active_records' - Add method 'domain.redirect_create_record' - Add method 'domain.redirect_delete_record' - Add method 'domain.redirect_update_record' - Add method 'domain.redirect_get_active_records' - Add internal methods
0.5.4	- Add method 'server.get_traffic_graph' - Update internal methods

Method Specifications

Introduction

The following part contains information about method calls, method parameters and method return values.
Generally, if a method call was completed successfully, the return message will include the following status code:

Field	Type	Value
status	int	100

If a method call was failed, a XML-Fault message with “Fault-Code” and “Fault-String” will be returned.(See also chapter “XML Fault-Codes”)

API Debug/Testing Methods

debug.get_api_version

PURPOSE

This Method returns the current API version.

CALL PARAMETERS

N/A

RETURNS

Field	Type	Description
api_version	string	Current API version

PHP EXAMPLE

 
<?php
//includes the class library
include_once("lib/xmlrpc.inc");
$xmlrpc_internalencoding = 'UTF-8';
$host="api.test.euserv.net";
$port=443;
$username="<API_USER>";
$password="<API_USER_PASSWORD>";
$api_path="/";
//defines the function
function debug_get_api_version($host,$port,$username,$password,$api_path)
{
//creates the serverurl
$serverurl = 'https://'.$host.':'.$port.'/'.$api_path;
//----------creates the message which will be send to the server----------
//creates the request for the XML-RPC Server
$request = new xmlrpcmsg('debug.get_api_version');
//adds parameters to the request
$request->addParam
(
//creates a value of type struct which contains an array with the username and password
new xmlrpcval
(
array
(
//creates a value of type string which contains the "$username"
'login' => new xmlrpcval($username, 'string'),
//creates a value of type string which contains the "$password"
'password' => new xmlrpcval($password, 'string')
)
,'struct'
)
);
//----------creates the XML-RPC client which represent a client of an XML-RPC server----------
//creates the client
$client = new xmlrpc_client($serverurl);
//disable SSL Keycheck
$client->setSSLVerifyPeer(0);
//----------sends the request to the server and gets the response----------
//sends the request via https and writes it into $response. timeout is set to 0
$response = $client->send($request,0,'https');
//generates a storable representation of $response and writes it into $result_xml
//$result_xml = $response->serialize();
//checks the response. if the method "faultCode" returns zero, the response was succesfull
if (0==$response->faultCode())
{
//returns the value sent by the server
$value = $response->value();
//returns the actual PHP-language value of "value"
$result_obj = $value->scalarval();
//destroys "value"
unset($value);
}
else
{
//returns the faultCode and the faultString
return $error = array ( 'faultCode' => $response->faultCode(), 'faultString' => $response->faultString());
}
//destroys "client"
unset($client);
//destroys "response"
unset($response);
//----------reads the result_obj----------
//if result_obj is set then it returns the actual PHP-language value of "result_obj"
if (isset($result_obj['status']))
{
$value['status'] = $result_obj['status']->scalarval();
}
if (isset($result_obj['api_version']))
{
$value['api_version'] = $result_obj['api_version']->scalarval();
}
return $value;
}
//calls the function
$result = debug_get_api_version($host,$port,$username,$password,$api_path);
if(0==$result['faultCode'])
{
echo "Status: ".$result['status']." API-Version: ".$result['api_version'];
}
else
{
echo "faultCode: ".$result['faultCode']." faultString: ".$result['faultString'];
}
?>

debug.pingpong

PURPOSE

This Method returns all the parameters, it was called with. You can use it to check the format of your call parameters. Notice that only supported parameter keys with correctly formatted values will be accepted!

CALL PARAMETERS

Every supported parameter key; see parameters of other methods.

RETURNS

Every committed parameter with its committed value.

PHP EXAMPLE

 
<?php
//includes the class library
include_once("lib/xmlrpc.inc");
$xmlrpc_internalencoding = 'UTF-8';
$host="api.test.euserv.net";
$port=443;
$username="<API_USER>";
$password="<API_USER_PASSWORD>";
$api_path="/";
$parameter="srv_id";
$wert = "1337";
//defines the function
function debug_pingpong($host,$port,$username,$password,$api_path,$parameter,$wert)
{
//creates the serverurl
$serverurl = 'https://'.$host.':'.$port.'/'.$api_path;
//----------creates the message which will be send to the server----------
//creates the request for the XML-RPC Server
$request = new xmlrpcmsg('debug.pingpong');
//adds parameters to the request
$request->addParam
(
//creates a value of type struct which contains an array with the username and password
new xmlrpcval
(
array
(
//creates a value of type string which contains the "$username"
'login' => new xmlrpcval($username, 'string'),
//creates a value of type string which contains the "$password"
'password' => new xmlrpcval($password, 'string'),
//creates a value of type string which contains the "$parameter"
$parameter => new xmlrpcval($wert)
)
,'struct'
)
);
//----------creates the XML-RPC client which represents a client of a XML-RPC server----------
//creates the client
$client = new xmlrpc_client($serverurl);
//disable SSL Keycheck
$client->setSSLVerifyPeer(0);
//----------sends the request to the server and gets the response----------
//sends the request via https and writes it into $response. timeout is set to 0
$response = $client->send($request,0,'https');
//generates a storable representation of $response and writes it into $result_xml
//$result_xml = $response->serialize();
//checks the response. if the method "faultCode" returns zero, the response was succesfull
if (0==$response->faultCode())
{
//returns the value sent by the server
$value = $response->value();
//returns the actual PHP-language value of "value"
$result_obj = $value->scalarval();
//destroys "value"
unset($value);
}
else
{
//returns the faultCode and the faultString
return $error = array ( 'faultCode' => $response->faultCode(), 'faultString' => $response->faultString());
}
//destroys "client"
unset($client);
//destroys "response"
unset($response);
//----------reads the result_obj----------
//if result_obj is set then it returns the actual PHP-language value of "result_obj"
if (isset($result_obj['status']))
{
$value['status'] = $result_obj['status']->scalarval();
}
if (isset($result_obj[$parameter]))
{
$value[$parameter] = $result_obj[$parameter]->scalarval();
}
return $value;
}
//calls the function
$result = debug_pingpong($host,$port,$username,$password,$api_path,$parameter,$wert);
if(!($result['faultCode']))
{
echo "Status: ".$result['status']." ".$parameter.": ".$result[$parameter];
}
else
{
echo "faultCode: ".$result['faultCode']." faultString: ".$result['faultString'];
}
?>

API User-Management Methods

usermngt.create_acc

PURPOSE

This Method is used to create new API user accounts

CALL PARAMETERS

Field / Key Name	Type	Description
acc_sub_id	string	Name of the new account; will be attached to management account's name separated by a point. (e.g. 'subacc' will become api123.subacc) Required are 3-8 chars [a-z] or [0-9]
acc_passwd_base64	string base64	Password for the new account (has to be base64-encoded) acc_ipv4_bindings string At least one allowed IPv4 address for using the new account. You can specify multiple values; each separated by a semicolon. Network-addresses and IPranges will not work.
acc_allowed_groups (optional)	string	Method group memberships for this account. Management account needs permissions for every mentioned group. You can specify multiple

RETURNS

Field / Key Name	Type	Description
acc_name	string	The complete name of the new account (e.g. 'api1234.subacc')
acc_added_ip_bindings	int	Number (amount) of added IP bindings
acc_added_groups	int	Number (amount) of added group memberships

usermngt.modify_acc

PURPOSE

This Method is used to modify settings and/or permissions of API user accounts.

CALL PARAMETERS

Field / Key Name	Type	Description
acc_id	string	Complete name of the account which will be modified (e.g. 'acc_id' => 'api1234.subacc')
acc_passwd_base64 (optional)	string base64	New account password in base64-encoded format. Using this parameter will overwrite the old password.
acc_ipv4_bindings (optional)	string	At least one allowed IPv4 address for using the new account. You can specify multiple values; each separated by a semicolon. Networkaddresses and IP-ranges will not work. You can specify multiple values, each separated by a semicolon. Using this parameter will overwrite old bindings.
acc_allowed_groups (optional)	string	This parameter will set method group memberships for the account and overwrite existing ones. Management account needs permissions for every mentioned group. You can specify multiple values, each separated by a semicolon. (e.g. 'acc_allowed_groups' => 'domain;server;vserver')
acc_status (optional)	string enum	Parameter to deactivate or to (re-)activate theParameter to deactivate or to (re-)activate the account Value must be “active” or “inactive”

RETURNS

Field / Key Name	Type	Description
acc_password_changed	bool	Shows if password has changed or not
acc_ip_bindings_changed	bool	Shows if IP bindings have changed or not
acc_groups_changed	bool	Shows if group memberships have changed or not
acc_status_changed	bool	Shows if account's status has changed or not (has set active or inactive)

usermngt.list_acc

PURPOSE

This Method is used to get all API user accounts and their settings/details

CALL PARAMETERS

N/A

RETURNS

Field / Key Name

Type

Description

acc_list_count

int

Number (amount) of available API user accounts

acc_list_data

array asoc

Contains all the account data in a multidimensional, associative array.

Array’s keys equals API user’s login names, e.g. $array ['api1234.subacc']

Values are contained in the second dimension, e.g. $array ['api1234.subacc'] ['status']

acc_list_data – Keys of second dimension

Key Name	Type	Description
status	string	Account’s status, can be “active” or “inactive”
created	string	“Datetime” of account creation
lastchange	string	“Datetime” of account’s last change groups array Contains all active method group names (e.g. 0 => “server”, 1 => “vserver”)
ip_bindings	array	Contains all active IP bindings (IP restrictions)

Server-related Methods

server.list_servers

PURPOSE

This Method is used to get all manageable servers and basic details for further method calls. Only these servers which are manageable by the used API user will be returned.

CALL PARAMETERS

N/A

RETURNS

Field / Key Name	Type	Description
server_list_count	int	Number (amount) of available servers
server_list_data	array asoc	Contains basic server details in a multidimensional, associative array. Keys of the first dimension equals the server order numbers: e.g. $array ['123456'] Values are contained in the second dimension: e.g. $array ['12345'] ['srv_main_ip'] returns the main

server_list_data – Keys of second dimension

Key Name	Type	Description
order_desc	string	Description/Product name
srv_id	int	Server’s unique ID (required for further method calls)
srv_main_ip	string	Primary IP address
srv_name	string	Server name (for network settings)
status	string enum	Server or order status: - “ready” means server can be used - “in_rescue” means server can be used but it’s currently in rescue mode - “in_process” means server is not available at present - “locked” means server/order is locked by the provider

PHP EXAMPLE

 
<?php
//includes the class library
include_once("lib/xmlrpc.inc");
$xmlrpc_internalencoding = 'UTF-8';
$host="api.test.euserv.net";
$port=443;
$username="<API_USER>";
$password="<API_USER_PASSWORD>";
$api_path="/";
//defines the function
function server_list_servers($host,$port,$username,$password,$api_path)
{
//creates the serverurl
$serverurl = 'https://'.$host.':'.$port.'/'.$api_path;
//----------creates the message which will be send to the server----------
//creates the request for the XML-RPC Server
$request = new xmlrpcmsg('server.list_servers');
//adds parameters to the request
$request->addParam
(
//creates a value of type struct which contains an array with the username and password
new xmlrpcval
(
array
(
//creates a value of type string which contains the "$username"
'login' => new xmlrpcval($username, 'string'),
//creates a value of type string which contains the "$password"
'password' => new xmlrpcval($password, 'string'),
)
,'struct'
)
);
//----------creates the XML-RPC client which represents a client of a XML-RPC server----------
//creates the client
$client = new xmlrpc_client($serverurl);
//disable SSL Keycheck
$client->setSSLVerifyPeer(0);
//----------sends the request to the server and gets the response----------
//sends the request via https and writes it into $response. timeout is set to 0
$response = $client->send($request,0,'https');
//generates a storable representation of $response and writes it into $result_xml
//$result_xml = $response->serialize();
//checks the response. if the method "faultCode" returns zero, the response was succesfull
if (0==$response->faultCode())
{
//returns the value sent by the server
$value = $response->value();
//returns the actual PHP-language value of "value"
$result_obj = $value->scalarval();
//destroys "value"
unset($value);
}
else
{
//returns the faultCode and the faultString
return $error = array ( 'faultCode' => $response->faultCode(), 'faultString' => $response->faultString());
}
//destroys "client"
unset($client);
//destroys "response"
unset($response);
//----------reads the result_obj----------
//if result_obj is set then it returns the actual PHP-language value of "result_obj"
if (isset($result_obj['status']))
{
$value['status'] = $result_obj['status']->scalarval();
}
if (isset($result_obj['server_list_count']))
{
$value['server_list_count'] = $result_obj['server_list_count']->scalarval();
}
if (isset($result_obj['server_list_data']))
{
$i=0;
//reads the data
do
{
//gets the server_order_number
$number = $result_obj['server_list_data']->structEach();
$i=$i+1;
$data = $result_obj['server_list_data']->scalarval();
//reads the value off the server_order_number
$data = $data[$number[0]]->scalarval();
//reads the value of each member and writes it into an array
$server_list_data[$number[0]]['srv_name'] = $data['srv_name']->scalarval();
$server_list_data[$number[0]]['srv_id'] = $data['srv_id']->scalarval();
$server_list_data[$number[0]]['order_desc'] = $data['order_desc']->scalarval();
$server_list_data[$number[0]]['srv_main_ip'] = $data['srv_main_ip']->scalarval();
$server_list_data[$number[0]]['status'] = $data['status']->scalarval();
}
while($i<$value['server_list_count']);
//writes the array "server_list_data" into the array "value"
$value['server_list_data'] = $server_list_data;
}
return $value;
}
//calls the function
$result = server_list_servers($host,$port,$username,$password,$api_path);
if(0==$result['faultCode'])
{
echo "Status: ".$result['status']." server_list_count: ".$result['server_list_count']."<br><br>";
//writes the array "server_list_data" into "daten"
$daten = $result["server_list_data"];
//gets the array_keys(members) of "daten"
$datenkeys = array_keys($daten);
$k=0;
//counts the arraykeys, the number of arraykeys will be used in the do-while construct
$anzahlkeys = count($datenkeys);
do
{
//outputs the data
echo " <u>server_order_number:</u> ".$datenkeys[$k];
echo " <u>srv_name:</u> ".$daten[$datenkeys[$k]]['srv_name'];
echo " <u>srv_id:</u> ".$daten[$datenkeys[$k]]['srv_id'];
echo " <u>order_desc:</u> ".$daten[$datenkeys[$k]]['order_desc'];
echo " <u>srv_main_ip:</u> ".$daten[$datenkeys[$k]]['srv_main_ip'];
echo " <u>status:</u> ".$daten[$datenkeys[$k]]['status'];
echo "<br>";
$k=$k+1;
}
while($k<$anzahlkeys);
}
else
{
echo "faultCode: ".$result['faultCode']." faultString: ".$result['faultString'];
}
?>

server.get_details

PURPOSE

This Method is used to get all details of a manageable server. Only these servers are available, which are manageable by the used API.

CALL PARAMETERS

Field / Key Name	Type	Description
srv_id	int	Server's unique ID

RETURNS

Field / Key Name	Type	Description
server_details	array (asoc)	Contains all server details in an associative array

server_details – Keys of second dimension

Key Name	Type	Description
order_no	int	Server contract’s order number
order_desc	string	Description/Product name
srv_id	int	Server’s unique ID (required for further method calls)
srv_main_ip	string	Primary IP address
srv_name	string	Server name (for network settings)
srv_netmask	string	Netmask for network / IP address setup
srv_broadcast	string	Broadcast address for network / IP address setup
srv_gateway	string	Gateway address for network / IP address setup
srv_status	string enum	Server or order status: - “ready” means server can be used - “in_rescue” means server is currently in rescue mode - “in_process” means server is not available at present - “locked” means server/order is locked by the provider
srv_default_pw	string	Default password for initial login or rescue usage
srv_mac	string	MAC-Address of server’s first network device
srv_mac2 (optional)	string	MAC-Address of server’s optional second network device
srv_cpu	string	Processor (Product) name / Description
srv_cpu_cores	int	Number of (available) CPU cores
srv_cpu_mhz	int	CPU clock rate in MHz srv_64bit_support bool CPU support for 64bit (true or false)
srv_ram_type	string	Type of used memory (e.g. DDR2-RAM)
srv_ram_size	int	Size of memory in MB
srv_hdd_type	string	Harddisk bus type (e.g. SATA)
srv_hdd_size	int	Size of each hdd (e.g. 250)
srv_hdd_count	int	Number of installed harddisks
srv_has_hwraid	bool	Hardware-RAID support (true or false)
srv_hwraid_level	string	Used Hardware-RAID level (“none” or level, e.g. “1”)
srv_os_id	int	ID of currently used OS image (for reinstall)
srv_os_name	string	Name/description of currently used OS image
srv_os_is_64bit	bool	OS image 64bit support (true or false)

Ansichten

Persönliche Werkzeuge

Navigation

Werkzeuge

API Documentation/en

Aus EUserv Wiki

Inhaltsverzeichnis

EUserv Reseller API

Introduction

Technology

API Servers

PHP Examples

History of Changes

Method Specifications

Introduction

API Debug/Testing Methods

debug.get_api_version

PURPOSE

CALL PARAMETERS

RETURNS

PHP EXAMPLE

debug.pingpong

PURPOSE

CALL PARAMETERS

RETURNS

PHP EXAMPLE

API User-Management Methods

usermngt.create_acc

PURPOSE

CALL PARAMETERS

RETURNS

usermngt.modify_acc

PURPOSE

CALL PARAMETERS

RETURNS

usermngt.list_acc

PURPOSE

CALL PARAMETERS

RETURNS

acc_list_data – Keys of second dimension

Server-related Methods

server.list_servers

PURPOSE

CALL PARAMETERS

RETURNS

server_list_data – Keys of second dimension

PHP EXAMPLE

server.get_details

PURPOSE

CALL PARAMETERS

RETURNS

server_details – Keys of second dimension