Спецификация взаимодействия по API

Актуальная версия используемой спецификации JSON-RPC 2.0 (http://www.jsonrpc.org/specification)

• Обращение к API
• Получение токена взаимодействия с API
• Формат запроса
• Формат ответа

Обращение к API

Обращение к API происходит по протоколу HTTP/HTTPS и использует метод POST передачи данных в виде JSON. В самом запросе URI указывает на объект (класс), а тело запроса содержит метод этого класса и параметры вызова.

Метод по умолчанию для всех объектов "index".

Получение токена для взаимодействия с API

Для большинства запросов к API вам потребуется передавать токен, полученный после авторизации. Получить токен можно отправив следующий запрос на URL https://api.sweb.ru/notAuthorized/

{"jsonrpc":"2.0","method":"getToken","params":{"login":"< >","password":"< >"}}

Где:

• <ваш логин> - логин в Личный кабинет аккаунта
• <ваш пароль> - пароль в Личный кабинет аккаунта

В ответе в параметре result придет токен, который нужно будет передавать при взаимодействии с API. Пример запроса и ответа:

curl  -H 'Content-Type: application/json; charset=utf-8' \
      -H 'Accept: application/json' \
      --data '{"jsonrpc":"2.0","method":"getToken","params":{"login":"vkireev166","password":"

Kmm3sWd5fkZws$hd"}}' \
      https://api.sweb.ru/notAuthorized/

{"jsonrpc":"2.0","version":"1.127.20220504121319","id":"20220505104244.40FxsQ16Ff","result":"
hdlhcdkd0bid6c29fhfu1s7rtu.202357ec-d5ca-4a0a-846c-2dabe0266ef4"}

Формат запроса

Пример формата запроса.

Request URL: https://api.sweb.ru/domains/ (обращение к объекту класса Domains)

Заголовки запроса

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: Bearer <,   >

Все запросы должны содержать заголовок с токеном авторизации, кроме запросов к общедоступным методам https://api.sweb.ru/notAuthorized/

POST данные в запросе:

{"jsonrpc":"2.0","version":"1.62.20210215150032","method":"add","params":{"domain":"vpstest.ru"},"id":"
20183994338.43VSEkfGFh","user":"vhphpunit"}

Описание параметров:

• jsonrpc - текущая версия JSON-RPC
• version - текущая версия клиента приложения. Носит только информационный характер, используется в отчетах об ошибках method - публичный метод объекта Domains
• params - ассоциативный массив параметров метода (ключ элемента массива - имя параметра)
• id - уникальный идентификатор запроса
• user - идентификатор пользователя, который отправляет запрос. Носит только информационный характер, сверяется со значением сессии токена и в случае расхождения приводит к ошибке авторизации

Параметр jsonrpc является обязательным. Если не передан id, то он будет сформирован на стороне API. Если не передан method будет вызван дефолтный метод для объекта.

Формат ответа

Успешный ответ

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

{"jsonrpc":"2.0","version":"1.62.20210215150032","id":"20183995523.MO4E9baKRr","result":{"balance":
{"real_balance":500,"bonus_balance":0}}}

Описание параметров:

• jsonrpc - текущая версия JSON-RPC
• version - текущая версия клиента
• result - результат, который возвращает вызванный метод
• id - уникальный идентификатор ответа, если был в запросе, то совпадает с ним

Все параметры в ответе являются обязательными.

Сообщение об ошибке

В случае возникновения ошибок, ответ вместо параметра result будет содержать error с двумя значениями code и message. Например:

{"jsonrpc":"2.0","version":"0.1","id":"20183910121.UPNWsDxwmn","error":{"code":-32601,"message":"Object not
found"}}

Описание параметров:

• jsonrpc - текущая версия JSON-RPC
• version - текущая версия клиента
• error - объект ошибки, который содержит (code - код ошибки http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php и message - текст ошибки)
• id - уникальный идентификатор ответа, если был в запросе, то совпадает с ним

Все параметры в ответе являются обязательными. Важно: HTTP-код ответа при этом всегда будет 200 Расширенное сообщение о результатах работы метода

Если метод кроме успешного или неуспешного результата должен передать клиенту какое-то кастомизированное сообщение или данные, то применяется общий тип ExtendedResult для таких ответов. Например:

{"jsonrpc":"2.0","version":"1.62.20210215150032","id":"20183995523.MO4E9baKRr","result":{"extendedResult":
{"code":1,"message":"\u0417\u0430\u044f\u0432\u043a\u0430 #180047823 \u043f\u0440\u0438\u043d\u044f\u0442\u0430
\u0432 \u0440\u0430\u0431\u043e\u0442\u0443","data":[]}}}

{"jsonrpc":"2.0","version":"1.62.20210215150032","id":"20183995523.MO4E9baKRr","result":{"extendedResult":
{"code":0,"message":"\u0417\u043e\u043d\u0430 .child \u043d\u0435
\u043f\u043e\u0434\u0434\u0435\u0440\u0436\u0438\u0432\u0430\u0435\u0442\u0441\u044f \u0434\u043b\u044f
\u0440\u0435\u0433\u0438\u0441\u0442\u0440\u0430\u0446\u0438\u0438","data":[]}}}

Описание параметров extendedResult:

• code - 1 - успешное выполнение, 0 - ошибка
• message - кастомизированное сообщение о результате
• data - объект дополнительных данных (может быть пустым)