API Documentation/en
Aus EUserv Wiki
Inhaltsverzeichnis |
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/.
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']
|
