Introduction

Technology

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 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 / Key Name

Type

Description

api_version

string

Current API version

PHP EXAMPLE

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!

API User-Management Methods

usermngt.create_acc

PURPOSE

CALL PARAMETERS

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.

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

Field / 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

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

PHP EXAMPLE

server.get_possible_failover_servers

PURPOSE

This method is used to get all possible servers, which are applicable for failover ip assignments, i.e. which have the failover ip feature enabled. Only servers which are manageable by the used API user will be returned.

CALL PARAMETERS

N/A

RETURNS

Field / Key Name

Type

Description

failover_server_list_count

int

Number (amount) of available servers, which are applicable for failover ip assignments

PHP EXAMPLE

server.get_possible_os_images

PURPOSE

This Method is used to get all possible OS images for a specific server ID. Only compatible and usable OS images will be returned here.

CALL PARAMETERS

Field / Key Name

Type

Description

srv_id

int

Server's unique ID

RETURNS

Field / Key Name

Type

Description

os_images_asoc_array

array asoc

Contains details of every possible/available OS image in a multidimensional, associative array. Keys of the first dimension equals the OS image number, called “os_id”: e.g. $array ['240'] Values are contained in the second dimension: e.g. $array ['240'] ['os_name'] returns the name/description of OS image with ID 240.

CALL PARAMETERS

RETURNS

PHP EXAMPLE

server.autoreinstall

PURPOSE

This Method is used to perform an automatic server reinstall with a specified OS image ID. Only compatible images will be accepted – you can obtain a list of all compatible OS images by using the “server.get_possible_os_images” API method.

CALL PARAMETERS

Field / Key Name

Type

Description

srv_id

int

Server’s unique ID

srv_os_id

int

ID of target OS image

srv_perform_reset

bool

Perform automatic server reset, to start installation? (“true” or “false”) If you choose “false” here, you have to perform

PHP EXAMPLE

server.order_server

PURPOSE

This method is used to order some server. Please note that this function only available for Reseller.

CALL PARAMETERS

Field / Key Name

Type

Description

<item_id>

int

Use the item_id of the serveritem you want to order as a key and the quantity of the server as the value eg. '11716' => '1' (order one server with the item_id '11716')

accept_terms_and_conditions

bool

Set this flag to accept the terms and conditions(0 = NO, 1= YES). If you don't accept the terms and conditions, you can't order server. The terms and conditions can be found here:http://euserv.de/unternehmen/agb.php

accept_special_terms_and_conditions_rootserver

bool

Set this flag to accept the spezial terms and conditions rootserver(0 = NO, 1= YES). If you don't accept the spezial terms and conditions rootserver, you can't order server. The spezial terms and conditions rootserver can be found here:http://euserv.de/produkte/server/tosfdrs.php

RETURNS

Field / Key Name

Type

Description

total_amount

string

The total amount for the server you have ordered

METHOD ERRORS

Code

Short Message

Description

1001

can not load customer_id

Error while loading the customer_id from api-user. Please contact the support!

1002

can not load a_id

Error while laoding the as_id from api-user. Please contact the support!

1003

terms and conditions must be accepted

To order server you must accept the terms and conditions.

1004

special terms and conditions rootserver must be accepted

To order server you must accept the spezial terms and conditions rootserver.

PHP EXAMPLE

vServer-related Methods

vserver.list_vservers

PURPOSE

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

CALL PARAMETERS

N/A

RETURNS

Field / Key Name

Type

Description

vserver_list_count

int

Number (amount) of available vservers

vserver_list_data

array asoc

Contains basic vserver details in a multidimensional, associative array. Keys of the first dimension equals the vserver order numbers: e.g. $array ['123456'] Values are contained in the second dimension: e.g. $array ['12345'] ['vsrv_main_ip'] returns the main

vserver_list_data – Keys of second dimension

Field / Key Name

Type

Description

order_desc

string

Description/Product name

vsrvord_id

int

vServer’s unique ID (required for further method calls)

vsrv_main_ip

string

Primary IP address

vsrv_name

string

vServer name (for network settings)

status

string enum

vServer or order status: - “ready” means vserver can be used - “in_rescue” means vserver can be used but it’s currently in rescue mode - “in_process” means vserver is not available at present - “locked” means vserver/order is locked by the provider

PHP EXAMPLE

vserver.get_details

PURPOSE

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

CALL PARAMETERS

Field / Key Name

Type

Description

vsrvord_id

int

vServer's unique ID

RETURNS

Field / Key Name

Type

Description

vserver_details

array (asoc)

Contains all vserver details in an associative array

vserver_details – Keys of second dimension

Key Name

Type

Description

order_no

int

vServer contract’s order number

order_desc

string

Description/Product name

vsrvord_id

int

vServer’s unique ID (required for further method calls)

vsrv_main_ip

string

Primary IP address

vsrv_name

string

vServer name (for network settings)

vsrv_name_reverse

string

vServer reversename (for network settings)

vsrv_netmask

string

Netmask for network / IP address setup

vsrv_broadcast

string

Broadcast address for network / IP address setup

vsrv_gateway

string

Gateway address for network / IP address setup

vsrv_status

string enum

vServer or order status:- “ready” means vserver can be used - “in_rescue” means vserver is currently in rescue mode - “in_process” means vserver is not available at present- “locked” means vserver/order is locked by the provider