Как работает Beget.API?

Всем привет!

В наших социальных сетях всё чаще появляются вопросы о работе Beget.API. Сегодня мы хотим подробнее рассказать про основные принципы работы API и как он делает работу с хостингом проще и удобнее.

API (Application Programming Interface) – программный интерфейс или набор функций для взаимодействия двух разных программ друг с другом.

API чаще всего используют программисты и разработчики, но протестировать эту функцию может любой желающий пользователь.

Beget.API позволяет воспользоваться большинством функций панели управления хостингом из своих собственных скриптов, систем управления сайтами (CMS) или других программных продуктов.

Что можно сделать, используя Beget.API?

Получить информацию о хостинг-аккаунте;
Управлять резервными копиями;
Управлять планировщиком заданий;
Производить настройку DNS;
Управлять базами данных;
Создавать и удалять сайты на аккаунте;
Управлять настройками доменов;
Управлять почтовыми ящиками и другое.

Для взаимодействия с API можно использовать протоколы HTTP или HTTPS. Мы рекомендуем HTTPS для безопасного соединения.

Методы API - это набор обработчиков, с которыми можно взаимодействовать во внутренней сети и через Интернет по протоколу HTTP/HTTPS.

Результатом работы с методом может быть получение информации (например, списка доменов на аккаунте, баланса и времени до блокировки) или выполнение каких-либо действий (например, удаление домена с аккаунта).

Передача параметров при отправке HTTP/HTTPS-запросов производится в составе URL в контексте GET-запроса, а результат выполнения запроса может возвращается обработчиком в разных форматах, главное, чтобы они были согласованы обеими сторонами соединения.

Браузер отлично отображает JSON-ответ, который вполне можно использовать в своём коде. Из такого текста достаточно просто извлечь данные, чтобы использовать их по своему усмотрению.

Чтобы начать подключение, в адресную строку браузера можно ввести URL следующего вида:

Рассмотрим работу на примере метода getAccountInfo() - с его помощью можно быстро получить краткую информацию об аккаунте.

Подробнее расскажем об этом далее в тексте.

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

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

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

Важно: в случае, если в настройках аккаунта вы задали отдельный пароль для API, для подключения нужно будет вводить именно его. При обращении с переданным паролем от аккаунта на хостинге будет отображаться ошибка о некорректном пароле.

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

Параметрами запроса API являются опции, которые можно передать конечной точке (например, указать формат ответа или возвращаемую сумму), чтобы повлиять на ответ. Существует четыре типа параметров:

параметры заголовка;
параметры path;
параметры строки запроса;
параметры тела запроса.

Различные типы параметров часто документируются в отдельных группах на одной странице. Не все конечные точки могут содержать каждый тип параметра.

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

Важно: передаваемые параметры в GET-запросе (например, пароль) должны быть перекодированы с помощью urlencode: пароль: asd%(123

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

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

input_format - формат входных данных.

Этот параметр указывает, в каком формате будут предоставляться параметры для методов.

Значение по умолчанию: plain.

На данный момент поддерживаются следующие форматы:

plain - все аргументы передаются совместно с основными параметрами запроса,
json - все аргументы метода должны быть в формате json. JSON-строка помещается в основной параметр input_data. В случае, если отправляем данные GET-данные, они будут защищены urlencode.

Эта функция удобна, когда закодированная строка будет использоваться в запросе, как часть URL, также это удобный способ для передачи переменных другим страницам.

input_data - параметр, принимающий строку с аргументами метода (если был выбран формат входных данных отличный от plain);

output_format - параметр, задающий формат ответа от API. На данный момент поддерживается только формат json. Параметр необязателен.

Рассмотрим пример вызова метода, который упоминали ранее в статье. Он позволит вывести статистику по аккаунту: возвращает информацию о тарифном плане пользователя, о некоторых параметрах сервера, на котором пользователь размещается в данный момент, и используемых лимитах на нем.

Пример ответа:

В некоторых полях (например, plan_domain) может стоять значение 2147483647 - это означает, что лимита на этот параметр не существует.

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

Каждый ответ от API имеет поле status, в котором содержится статус запроса.
Если запрос выполнен успешно, то поле имеет значение success.
В этом случае результат выполнения метода содержится в соседнем поле answer:

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

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

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

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

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

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

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

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

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

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

Мы создавали Beget.API для удобства наших пользователей и рады, что его применяют на практике:

1. Один из наших пользователей написал модуль для “Bitrix” на базе Beget.API, посмотреть его можно по ссылке.

Этот модуль пригодится всем пользователям Beget. После установки модуля у Вас появится гаджет, который будет показывать:

- Баланс аккаунта пользователя;

- количество дней до блокировки;

- сколько места занимают ваши проекты и сколько дискового пространства вы можете использовать.

2. Также на основе Beget.API написана библиотека для PHP, смотрите её здесь.

В ней масса полезного функционала для управления нашими основными услугами: управление аккаунтом, бэкапами, сайтами, CRON и многое другое.

В статье мы подробно рассказали про API: чем API может быть полезен, какие бывают параметры запроса с примерами ответов на них, также мы подробно погрузились в методы и коды ошибок. Пусть статья станет источником информации и выведет взаимодействие с хостингом на новый уровень, сделав работу быстрей и приятней.

Если у вас остались вопросы, вы всегда можете задать их в комментариях, мы оперативно ответим, а если будет нужно, призовём в комментарии нужных специалистов. 🤗

Как работает Beget.API?

Report Page