API Friendhosting

Contents

1. Introduction
2. HTTP Gateway Description
2.1. Real Access
2.2. Test Access
3. Sending HTTP Requests
3.1. Commands
3.2. Input Data Format
3.3. Command Execution Results’ Format
3.4. General Request Fields
3.5. Error Notifications
3.6. Authentication Methods
3.6.1. Password-Based Authentication
3.6.2. Authentication Based on the API Key
4. Commands’ Description
4.1. Creating an Order
4.2. Renewing an Order
4.3. Suspending an Order
4.4. Starting a Suspended Order
4.5. Viewing the Tariff Plan List
4.6. Restarting an Order
4.7. Reinstalling an Order
4.8. Getting the List of Orders
4.9. Getting the User’s Balance

1. Introduction

This instruction manual describes the HTTP gateway to the distributed registration system(hereinafter API).
HTTP gateway is a method of interacting with the distributed registration system API. It allows making operations in real time in just one step.

To carry out one-step (one-stage) operations, all the information has to be included in one HTTP request. The API interface doesn’t recognize states, and all requests are independent from one another. The HTTP interface supports such operations as creating an order, prolonging an order, suspending an order, launching an order and more. The available operations are described further in this document.

2. HTTP Gateway Description

provides not only the real access to the HTTP gateway but also the test access to debug interaction with the system API.

2.1. Real Access

Requests to the HTTP gateway have to be directed at the following URL: https://my.friendhosting.net/apih.php

2.2. Test Access

Friendhosting LTD provides test access to its gateway for testing the registration system. The test access is different from the real one in the following three ways:
– Operations are conducted free of charge
– Operations with orders are not actually done, accounts are not created
– The test system doesn’t contain order information available in the real registry.

To use the test system, HTTP requests have to be directed at the same URL as for the real system. In this case, use the following authorization data:
login: test
pass: test

3. Sending HTTP Requests

3.1. Commands

HTTP gateway allows conducting different commands. Below in the table you will find the list of commands that can be carried out using the HTTP gateway. You need to use specific parameters (fields) that are described below for each command.

Command
(command value)
Description
createOrderCreating a new order
renewOrderRenewing the order
suspendOrderSuspending an order
unSuspendOrderLaunching a suspended order
getTarifsGetting the list of tariff plans
restartOrderRestarting an order
reinstallOrderReinstalling an order
getOrdersGetting the list of orders

3.2. Input Data Format

The commands are transferred in the form of a standard HTTP/1.0 request using the POST or GET method. The command parameters are transferred as HTTP parameters. The following rules are applied in this case:
– All fields’ values are strings.
– All fields’ values are transferred in UTF-8 encoding.
– All required fields have to be included in the request and have to contain at least one character.
– HTTP parameters’ names have to match the names of the fields (capitalization is respected).
– All fields’ values have to be urlencoded.

3.3. Command Execution Results’ Format

The API interface answer is a serialized string containing a parameter array received using the PHP functions serialize. The response string is encoded using UTF-8. To convert the serialized string into a parameter array, you need to use the PHP function unserialize. There is also a possibility to get the answer in the JSON format.

3.4. General Request Fields

In this table you will find all the required fields that have to be included in any request.

Field NameDescription
commandDefines the command that has to be executed; for instance, createOrder
loginUser login in the billing system
passUser password in the billing system. Pass and apikey fields are mutually exclusive and can’t be included in the same request. More information in the section 3.6.
apikeyThe key for gaining access to the API interface. Pass and apikey fields are mutually exclusive and can’t be included in the same request. More information in the section 3.6.
jsonIf the field value is 1, the system will return the answer in the JSON format. The field is not obligatory.

3.5. Error Notifications

There are two types of errors – critical and non-critical. In the event of a critical error, it is considered that the command is not executed. In the event of a non-critical error, it is considered that the command is executed or will be executed later. In the event of an errors during command execution, API returns parameters listed in the table below.

Field NameDescription
statusThe result of command execution. In the event of a critical error, the value is always ERROR. In the event of a non-critical one, it is SUCCESS.
errorCodeError code.
errorMsgA detailed description of the error.

 

In the table below you will find possible critical errors you may encounter when working with the API.

Error CodeDescription
1Error in connection to the database
2Error in saving the data in the database
3User login is not stated
4User is not found
5API access is denied
6Password or API key is not stated
7The stated password or API key is not correct
8Unknown command
9It is prohibited to use the password and API key in the same request
10Tariff plans are absent
11Tariff plan identifier is not provided
12Tariff plan is not found
13Domain name is not provided
14The tariff plan for the stated domain name is already ordered
15The order period is not stated
16The order period stated is unacceptable
17The stated additional service is unacceptable
18The order identifier is not stated
19The order is not found
20There are unpaid bills for this order
21The order is already suspended
22The order is already started
23The order is expired
24The tariff plan type is not valid
25The operation is not supported for this type of orders
26Orders are absent
27The tariff plan can be ordered by one client only once
28The stated amount of the additional service is unacceptable
29You need to order an additional service from the group
54Access denied. IP address is not on the list of permissioned ones

 

IN the table below you will find possible non-critical errors you may encounter when working with API.

Error CodeDescription
30The order is placed, but due to technical reasons it will be processed manually.
31The order is placed, but it will be processed after the payment.

 

3.6. Authentication Methods

The API registration system supports two authentication methods: based on the login and passwords, or based on the API key.

3.6.1. Password-Based Authentication

Authentication is done using the request field login and pass. The user with the stated login and password has to exist in the billing system for the successful authentication. Besides, the said user has to have API access enabled for them.

3.6.2. Authentication Based on the API Key

Authentication is done using the request fields login and apikey. The user with the stated login and API key has to exist in the billing system for the successful authentication. Besides, the said user has to have API access enabled for them.

4. Commands’ Description

4.1. Creating an Order

This command is used for creating a new order. You need to use createOrder as a value for the field command of this operation.
In the table below you will find the fields used when creating an order.

Field NameDescription
vidTariff plan type. The acceptable values are: hosting, vds, dedicated. If the value is not stated, hosting is used by default.
tarifidTariff plan ID. The list of available tariff plans can be gained by executing the command described in 4.5.
periodPeriod for the created order. You can view the acceptable values for this field by executing the command described in 4.5.. The value has to be stated in months. Example: 1.
domainThe full domain name that the order is created for (for instance, example.com). Alphabet characters, digits, and hyphens are allowed. The Cyrillic domain names are stated in the UTF-8 encoding. The field is not required if the allowWithoutDomain parameter value is 1.
addonsID of the additional service that has to be attached to the order. Several IDs are separated by commas. The list of available additional services for each tariff plan can be viewed by executing the command described in 4.5. This field is not obligatory.

 

In the event of a successful command execution, API will return the fields listed in the table below.

Field NameDescription
statusIf the command is executed successfully, the value will always be SUCCESS.
orderidOrder ID in the API system. It is used for further order management.
vidThe type of tariff plan that was used for creating the order.
tarifidTariff plan ID in the API system that was used for creating the order.
domainThe domain name the order was created for.
periodThe period the order was created for.
addonsID of the additional services that were attached to the order.
balanceThe current user balance.
costOrder creation price.
currencyThe code of the currency used for the returned price and balance. It is identical to the currency of the user in the billing system.
serverloginAdditional data: the order login on the server.
serverpasswordAdditional data: the order password on the server.
remarkAdditional data: notes; the field may contain various additional information regarding the order.

 

4.2. Renewing an Order

This command is used for renewing an order. You need to use renewOrder as a value for the field command of this operation.
In the table below you will find the fields used when renewing an order.

Field NameDescription
orderidOrder ID in the API system which is returned by the command described in 4.1.
periodPeriod for the created order. You can view the acceptable values for this field by executing the command described in 4.5.. The value has to be stated in months. Example: 1.

 

In the event of a successful command execution, API will return the fields listed in the table below.

Field NameDescription
statusIf the command is executed successfully, the value will always be SUCCESS.
orderidOrder ID in the API system.
periodThe period the order was renewed for.
balanceThe current user balance.
costOrder renewal price.
currencyThe code of the currency used for the returned price and balance. It is identical to the currency of the user in the billing system.

4.3. Suspending an Order

This command is used for suspending an order. You need to use suspendOrder as a value for the field command of this operation.
In the table below you will find the fields used when suspending an order.

Field NameDescription
orderidOrder ID in the API system which is returned by the command described in 4.1.

In the event of a successful command execution, API will return the fields listed in the table below.

Field NameDescription
statusIf the command is executed successfully, the value will always be SUCCESS.
orderidOrder ID in the API system.

4.4. Starting a Suspended Order

This command is used for launching a suspended order. You need to use unSuspendOrder as a value for the field command of this operation.
In the table below you will find the fields used when launching a suspended order.

Field NameDescription
orderidOrder ID in the API system which is returned by the command described in 4.1.

In the event of a successful command execution, API will return the fields listed in the table below.

Field NameDescription
statusIf the command is executed successfully, the value will always be SUCCESS.
orderidOrder ID in the API system.

4.5. Viewing the Tariff Plan List

This command is used for getting a list of available tariff plans. You need to use getTarifs as a value for the field command of this operation.
In the table below you will find the fields used to get the list of tariff plans.

Field NameDescription
vidTariff plan type. The acceptable values are: hosting, vds, dedicated. If the value is not stated, hosting is used by default.

In the event of a successful command execution, API will return the fields listed in the table below.

Field NameDescription
statusIf the command is executed successfully, the value will always be SUCCESS.
tarifsThis field returns an array of fields. Each field of the array is, in its turn, an array and contains the following fields:
id – tariff plan ID
vid – tariff plan type
name – tariff plan name
costMonthly – tariff plan monthly price
costSetup – tariff plan installation cost
currency – the currency code used for the prices
allowWithoutDomain – if it’s value is 1, you can order this tariff plan without stating a domain name
months – a field array containing available order periods:
months – the order period in months
discount – the discount for this order period
allowForNewOrder – if it’s 1, you are allowed to use the order period for new orders
allowForRenew – if it’s 1, you are allowed to use the order period for renewing orders
addons – a field array containing available additional services:
id – additional service ID
name – additional service name
costMonthly – additional service monthly price
costSetup – additional service installation price

4.6. Restarting an Order

This command is used for restarting an order (server). The command is supported only by certain types of servers. You need to use restartOrder as a value for the field command of this operation.
In the table below you will find the fields used when restarting an order.

Field NameDescription
orderidOrder ID in the API system which is returned by the command described in 4.1.

 

In the event of a successful command execution, API will return the fields listed in the table below.

Field NameDescription
statusIf the command is executed successfully, the value will always be SUCCESS.
orderidOrder ID in the API system.

4.7. Reinstalling an Order

This command is used for reinstalling an order (server). The command is supported only by certain types of servers. You need to use reinstallOrder as a value for the field command of this operation.
In the table below you will find the fields used when reinstalling an order.

Field NameDescription
orderidOrder ID in the API system which is returned by the command described in 4.1.

In the event of a successful command execution, API will return the fields listed in the table below.

Field NameDescription
statusIf the command is executed successfully, the value will always be SUCCESS.
orderidOrder ID in the API system.

4.8. Getting the List of Order

This command is used for getting the list of the client’s orders. The command is supported only by certain types of servers. You need to use getOrders as a value for the field command of this operation.
In the table below you will find the fields used when getting the list of orders.

Field NameDescription
orderidOrder ID in the API system which is returned by the command described in 4.1.
Not a required field! If stated, only one order will be returned.

In the event of a successful command execution, API will return the fields listed in the table below.

Field NameDescription
statusIf the command is executed successfully, the value will always be SUCCESS.
ordersThis field returns a field array. Each array contains the following fields:
orderid – order ID
domain – domain name
domain_reg – 0 – without domain registration, 1 – with domain registration, 3 – with domain transfer
vid – tariff plan type
tarifid – tariff plan ID
tarifname – tariff plan name
orderdate – order placement date
startdate – order start date
todate – the date until which the order is paid for
leftdays – the number of days until the order’s end
status – order status (0 – not processed, 1 – processed, 2 – suspended, 3 – being processed)

4.9. Getting the User’s Balance

This command is used for viewing the sum on the balance of a billing system. You need to use getBalance as a value for the field command of this operation.

In the event of a successful command execution, API will return the fields listed in the table below.

Field NameDescription
statusIf the command is executed successfully, the value will always be SUCCESS.
balanceCurrent user balance.
currencyThe currency code of the returned balance. It is identical to the user currency in the billing system.
We use cookies. Read more - in our terms of use.