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 |
| createOrder | Creating a new order |
| renewOrder | Renewing the order |
| suspendOrder | Suspending an order |
| unSuspendOrder | Launching a suspended order |
| getTarifs | Getting the list of tariff plans |
| restartOrder | Restarting an order |
| reinstallOrder | Reinstalling an order |
| getOrders | Getting 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 Name | Description |
| command | Defines the command that has to be executed; for instance, createOrder |
| login | User login in the billing system |
| pass | User 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. |
| apikey | The 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. |
| json | If 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 Name | Description |
| status | The 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. |
| errorCode | Error code. |
| errorMsg | A detailed description of the error. |
In the table below you will find possible critical errors you may encounter when working with the API.
| Error Code | Description |
| 1 | Error in connection to the database |
| 2 | Error in saving the data in the database |
| 3 | User login is not stated |
| 4 | User is not found |
| 5 | API access is denied |
| 6 | Password or API key is not stated |
| 7 | The stated password or API key is not correct |
| 8 | Unknown command |
| 9 | It is prohibited to use the password and API key in the same request |
| 10 | Tariff plans are absent |
| 11 | Tariff plan identifier is not provided |
| 12 | Tariff plan is not found |
| 13 | Domain name is not provided |
| 14 | The tariff plan for the stated domain name is already ordered |
| 15 | The order period is not stated |
| 16 | The order period stated is unacceptable |
| 17 | The stated additional service is unacceptable |
| 18 | The order identifier is not stated |
| 19 | The order is not found |
| 20 | There are unpaid bills for this order |
| 21 | The order is already suspended |
| 22 | The order is already started |
| 23 | The order is expired |
| 24 | The tariff plan type is not valid |
| 25 | The operation is not supported for this type of orders |
| 26 | Orders are absent |
| 27 | The tariff plan can be ordered by one client only once |
| 28 | The stated amount of the additional service is unacceptable |
| 29 | You need to order an additional service from the group |
| 54 | Access 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 Code | Description |
| 30 | The order is placed, but due to technical reasons it will be processed manually. |
| 31 | The 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 Name | Description |
| vid | Tariff plan type. The acceptable values are: hosting, vds, dedicated. If the value is not stated, hosting is used by default. |
| tarifid | Tariff plan ID. The list of available tariff plans can be gained by executing the command described in 4.5. |
| period | Period 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. |
| domain | The 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. |
| addons | ID 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 Name | Description |
| status | If the command is executed successfully, the value will always be SUCCESS. |
| orderid | Order ID in the API system. It is used for further order management. |
| vid | The type of tariff plan that was used for creating the order. |
| tarifid | Tariff plan ID in the API system that was used for creating the order. |
| domain | The domain name the order was created for. |
| period | The period the order was created for. |
| addons | ID of the additional services that were attached to the order. |
| balance | The current user balance. |
| cost | Order creation price. |
| currency | The code of the currency used for the returned price and balance. It is identical to the currency of the user in the billing system. |
| serverlogin | Additional data: the order login on the server. |
| serverpassword | Additional data: the order password on the server. |
| remark | Additional 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 Name | Description |
| orderid | Order ID in the API system which is returned by the command described in 4.1. |
| period | Period 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 Name | Description |
| status | If the command is executed successfully, the value will always be SUCCESS. |
| orderid | Order ID in the API system. |
| period | The period the order was renewed for. |
| balance | The current user balance. |
| cost | Order renewal price. |
| currency | The 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 Name | Description |
| orderid | Order 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 Name | Description |
| status | If the command is executed successfully, the value will always be SUCCESS. |
| orderid | Order 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 Name | Description |
| orderid | Order 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 Name | Description |
| status | If the command is executed successfully, the value will always be SUCCESS. |
| orderid | Order 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 Name | Description |
| vid | Tariff 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 Name | Description |
| status | If the command is executed successfully, the value will always be SUCCESS. |
| tarifs | This 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 Name | Description |
| orderid | Order 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 Name | Description |
| status | If the command is executed successfully, the value will always be SUCCESS. |
| orderid | Order 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 Name | Description |
| orderid | Order 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 Name | Description |
| status | If the command is executed successfully, the value will always be SUCCESS. |
| orderid | Order 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 Name | Description |
| orderid | Order 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 Name | Description |
| status | If the command is executed successfully, the value will always be SUCCESS. |
| orders | This 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 Name | Description |
| status | If the command is executed successfully, the value will always be SUCCESS. |
| balance | Current user balance. |
| currency | The currency code of the returned balance. It is identical to the user currency in the billing system. |