Beget.API. Принципы работы с API. LTD Beget.

Способ взаимодействия

Взаимодействие с API происходит по протоколу HTTPS.

URL для вызова метода имеет вид:

https://api.beget.com/api/раздел/метод?параметры

Пример

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

Передача параметров, обязательные параметры

Как мы видим из предыдущего примера, методу было передано два параметра.

При вызове любого метода необходимо передавать как минимум два обязательных параметра:

login - логин пользователя;
passwd - пароль пользователя.

Дополнительные параметры запроса

Дополнительные параметры передаются стандартными средствами протокола HTTP, их можно передавать как методом GET, так и методом POST. Также можно комбинировать два этих способа.

Мы рекомендуем использовать метод POST, т.к. он не имеет ограничений по длине передаваемых параметров.

При вызове любого метода можно передавать следующие дополнительные параметры:

input_format - формат входных данных.
Этот параметр указывает, в каком формате будут предоставляться параметры для методов.
Значение по-умолчанию: plain.
На данный момент поддерживаются следующие форматы:
- plain - все аргументы передаются совместно с основными параметрами запроса, самый простой формат, однако рекомендуем использовать другие;
- json - все аргументы метода должны быть в формате json. JSON-строка помещается в основной параметр input_data;
input_data - параметр, принимающий строку с аргументами метода (если был выбран формат входных данных отличный от plain);
output_format - параметр, задающий формат ответа от API. На данный момент поддерживается только формат json. Значение по-умолчанию: json.

Пример вызова метода

Пример показывает вызов метода, который добавит test-domain домен в зоне с ID=1 (ru).

Следует обратить внимание, что JSON-строка в параметре input_data была закодирована методом urlencode (это обязательно для передачи спецсимволов по протоколу http).

В не закодированном виде строка input_data выглядит так: {"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

Обработка ответа

Общий результат выполнения запроса

Каждый ответ от API имеет поле status, в котором содержится статус запроса.

Если запрос выполнен успешно, то поле имеет значение success.

В этом случае результат выполнения метода содержится в соседнем поле answer:

{
	"status": "success",
	"answer": результат выполнения метода
}

Если запрос завершился с ошибкой, то поле status имеет значение error. В этом случае рядом с этим полем будут находится поля error_text(текст ошибки) и error_code (код ошибки):

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

Возможные коды ошибок

AUTH_ERROR - ошибка авторизации;
INCORRECT_REQUEST - ошибка, говорящая о некорректном запросе к API;
NO_SUCH_METHOD - указанного метода не существует.

Результат выполнения метода

Если запрос выполнен успешно, то поле result запроса будет содержать ответ от метода.

Результат метода также содержит свое поле status, которое также может принимать значение success или error.

Если результат выполнения метода положительный, то в соседнем поле result будет содержаться результат запроса (в примере приведен полный ответ):

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

Если результат выполнения метода отрицательный, то вместо поля result будет поле errors, которое будет содержать ошибки, произошедшие во время выполнения метода (в примере приведен полный ответ):

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

Смысл полей в каждой ошибке тот же самый, что и в ошибке запроса. Следует отметить, что ошибок может быть несколько. Код ошибки позволяет понять тип, к которому принадлежит ошибка.

Используемые коды ошибок

INVALID_DATA - ошибка валидации переданных данных;
LIMIT_ERROR - отказ в выполнении из-за достижения какого-либо лимита (например, превышен лимит сайтов или лимит запросов к API (не более 60 запросов в минуту для пользователя));
METHOD_FAILED - внутренняя ошибка при выполнении метода.