Basic principles of operation with API

Method of interaction

Interaction with API is performed via HTTPS protocol.

URL for method call looks as follows:

https://api.beget.com/api/section/method?parameters

Example:

https://api.beget.com/api/user/getAccountInfo?login=user&passwd=mypassword

Parameter passing, mandatory parameters

As we see from the previous example, two parameters have been passed to the method.

When calling any method, at least two mandatory parameters must be passed:

• login - user login;
• passwd - user password.

Additional call parameters

Additional parameters are passed via standard HTTP means. They can be passed both via GET method and POST method. These two methods can also be combined.

We recommend you to use the POST method since it has no limitations of length for passed parameters.

When calling any method, you can pass the following additional parameters:

• input_format - input data format.
  This parameter shows in which format parameters for methods will be given.
  Default value: plain.
  The following formats are currently supported:
  • plain - all arguments are passed together with the main call parameters, the plainest format, however we recommend using others;
  • json - all method arguments must be in json format. The JSON string needs to be put into the main parameter input_data;
• input_data - parameter, receiving string with method arguments (if input data format other than plain)
• output_format - parameter, defining output format from API. Currently only json format is supported. Default value: json.

Method call example

The example shows a call of the method, which adds the domain test-domain to the zone with ID=1 (de). Please note, in the parameter input_data the JSON string has been coded with the urlencode method (this is necessary for passing special characters via https protocol).
The uncoded input_data string looks as follows: {"hostname":"test-domain","zone_id":1}.

https://api.beget.com/api/domain/addVirtual?login=user&passwd=password&
input_format=json&output_format=json&input_data=
%7B%22hostname%22%3A%22test-domain%22%2C%22zone_id%22%3A1%7D

Response handling

General result of query execution

Each response from API has the field status, containing the query status.
If the query has been executed successfully, the field will have the value success.

In this case you will find the method execution result in the adjacent field answer:

{
    "status": "success",
    "answer": method execution result
}

If the query has been performed with an error, the field status will have the value error.

{
 	"status": "error",
 	"error_text": "No such method",
 	"error_code": "NO_SUCH_METHOD"
}

Possible error codes:

• AUTH_ERROR - authorization error;
• INCORRECT_REQUEST - error, indicating an incorrect request to API;
• NO_SUCH_METHOD - such method does not exist.

Method execution result

If the query has been executed successfully, the field result will contain a response from the method.
The method result also has its own status field, which in turn can have the value success or error.
If the method execution result is positive, the adjacent field result will contain the query result (the example shows the full response):

{
   "status":"success",
   "answer":{
      "status":"success",
      "result":[
         {
            "id":"125",
            "path":"site.de\/public_html",
            "domains":[
               {
                  "id":"12345",
                  "fqdn":"site.de"
               }
            ]
         },
         {
            "id":"124",
            "path":"vk.com\/public_html",
            "domains":[
 
            ]
         },
         {
            "id":"123",
            "path":"mysite\/public_html",
            "domains":[
 
            ]
         }
      ]
   }
}

If the method execution result is negative, you will see the field errors instead of result, which will contain errors, which occurred during the method execution (the example shows the full answer):

{
   "status":"success",
   "answer":{
      "status":"error",
      "errors":[
         {
            "error_code":"INVALID_DATA",
            "error_text":"Login length cannot be greater than 12 characters"
         }
      ]
   }
}

The fields in each error have the same sense as in the query error. Please note that there can be various errors. The error code allows to find out the error type.

Used error codes:

• INVALID_DATA - validation error of passed data;
• LIMIT_ERROR - execution failure due to reaching some kind of limit (e.g. limit of websites or limit of queries to API (max. 60 queries per minute for user) has been exceeded);
• METHOD_FAILED - internal error when executing method.