Ключевые слова: api, удалённая регистрация, авторизация |
Под интеграцией в данной статье мы понимаем процесс объединения информационной биллинговой системы JBs с использованием внешних веб-интерфейсов со сторонними информационными системами.
Содержание
[убрать]Описание интерфейса
Удалённый вызов функций системы JBs осуществляется с использованием протокола HTTP. Передача параметров может осуществляться как через GET так и через POST запросы. Обязательным для передачи всегда является параметр XMLHttpRequest=yes.
Ответы системы представлены в виде объектов формата JSON. Общий вид ответа выглядит следующим образом:
{Status:('Error','Exception','Ok'),Name1:Value1,Name2:Value2...}
Свойство Status присутствует во всех ответах системы и может принимать одно из трех указанных значений.
Виды ответа на запрос
- Если в процессе обработки запроса произошла ошибка (нет доступа к базе данных, ошибка работы с файловой системой и т.д.) - ответ системы будет выглядеть следующим образом:
{Status:'Error',Error:{CodeID:500,String:'Критическая ошибка'}}
- В случае, если в процессе обработки запроса произошло "исключение" (не верный формат входных данных, объект не найден в базе данных и т.д.) - ответ системы будет выглядеть как:
{Status:'Exception',Exception:{CodeID:'EXCEPTION_CODE',String:'Произошло исключение'}}
Исключение "ожидаемо", т.е. система уже была готова к тому что такая ситуация может произойти и среагировать на нее. Это отличает "исключения" от "ошибок". Каждый вызываемый модуль имеет свои исключения.
- Если системе успешно удалось обработать входящий запрос ответ будет следующим:
{Status:'Ok',Name1:Value1,Name2:Value2,...}
Ответ может содержать любые данные выдаваемые модулем.
Типы входных значений
- Число, строка передаются в стандартном виде:
http://domain/Module?String=hello&Number=100
- Массив - множество данных, передается в виде пар-значений:
http://domain/Module?Array[]=first&Array[]=second
Таким образом, массив Array состоит из 2х элементов [first,second]
- Логический - два значения ИСТИНА/ЛОЖ. Логический параметр считается ИСТИННЫМ, если он был передан с любым значением, если передача не осуществлялась, значение параметра по умолчанию устанавливается как ЛОЖ.
http://domain/Module?Logic=true
Для удаленного вызова функций Вы в начале должны пройти авторизацию. |
Авторизация в системе
Авторизация - совокупность двух этапов: идентификации и авторизации. Идентификация в системе JBs происходит с использованием электронного адреса и пароля пользователя.
Имя модуля | /API/Logon | |
Параметры | ||
Электронный адрес пользователя | Строка | |
Password | Пароль пользователя | Строка |
В случае успешного выполнения ответ будет выглядеть как:
{Status:'Ok',SessionID:'SESSION48e65f5de64e3',Home:'/Home'}
- SessionID - уникальный идентификатор сессии выданный системой, может быть в последующем передаваться системе для выполнения многократных запросов.
- Home - адрес домашней страницы пользователя. По умолчанию для всех клиентов устанавливается как /Home, для администраторов /Administrator/Home.
После успешной удаленной авторизации на вашем сайте, Вы можете перенаправить пользователя в систему:
Location: http(s)://domain{Home}?SessionID={SessionID}
Пример сценария авторизации на языке PHP:
<?php #------------------------------------------------------------------------------- $Email = 'admin@company.com'; $Password = 'default'; #------------------------------------------------------------------------------- $Request = SPrintF('http://joonte.com/API/Logon?XMLHttpRequest=yes&Email=%s&Password=%s',$Email,$Password); #------------------------------------------------------------------------------- $Answer = @File_Get_Contents($Request); if(!$Answer) Exit('Request error'); #------------------------------------------------------------------------------- $Answer = @JSON_Decode($Answer,TRUE); if(!$Answer) Exit('Bad answer'); #------------------------------------------------------------------------------- switch($Answer['Status']){ case 'Error': #--------------------------------------------------------------------------- $Error = $Answer['Error']; #--------------------------------------------------------------------------- Exit($Error['String']); case 'Exception': #--------------------------------------------------------------------------- $Exception = $Answer['Exception']; #--------------------------------------------------------------------------- Exit($Exception['String']); case 'Ok': #--------------------------------------------------------------------------- Header(SPrintF('Location: http://joonte.com%s?SessionID=%s',$Answer['Home'],$Answer['SessionID'])); #--------------------------------------------------------------------------- Exit; default: Exit('Wrong status'); } #------------------------------------------------------------------------------- ?>
Обновляемые примеры API на языке PHP
По запросам пользователей мы более точно описываем интерфейc API в постоянно обновляемом файле
http://joonte.com/Tests/API?Source
Он так же доступен на любой копии системы
hosts/hosting/comp/www/Tests/API.comp
Регистрация пользователя
Биллинговая система имеет защиту от автоматических регистраций с использованием ввода контрольной комбинации цифр. Для обеспечения нормального функционирования удаленных регистраций данная защита отключается, если запрос на регистрацию приходит с того же IP адреса, на котором размещен домен биллинговой системы. |
Имя модуля | /API/UserRegister | |
Параметры | ||
Электронный адрес пользователя | Строка | |
Password | Будущий пароль пользователя | Строка |
Name | Имя пользователя | Строка |
В случае успешного выполнения ответ будет выглядеть как:
{Status:'Ok',SessionID:'SESSION48e65f5de64e3',Home:'/Home',ContractID:1000,UserID:1000}
- SessionID - уникальный идентификатор сессии выданный системой, может быть в последующем передаваться системе для выполнения многократных запросов.
- Home - адрес домашней страницы пользователя. По умолчанию для всех клиентов устанавливается как /Home.
- ContractID - идентификатор договора по умолчанию. Может использоваться в дальнейших запросах.
- UserID - идентификатор пользователя. Может использоваться в дальнейших запросах.
Запрос информации из БД
Для доступа к модулю требуется авторизация одного из администраторов. |
Имя модуля | /Administrator/API/SelectDB | |
Параметры | ||
[+]TableID | Имя таблицы в базе данных | Строка |
ColumnsIDs | Список полей | Массив |
SortOn | Список полей сортировки | Массив |
IsDesc | Использовать обратный вывод | Логический |
Conditions | Условия выборки | Массив |
Limits | Ограничение вывода | Массив[начальный_индекс, кол-во_строк] |
Пример, вывод новостей из базы данных:
http://domain/Administrator/API/SelectDB?TableID=Clauses&ColumnsIDs[]=Title&ColumnsIDs[]=Text&Conditions[]=Partition=News&SortOn=PublicDate&IsDesc=true&Limits[]=10&Limits=40
В случае успешного выполнения ответ будет выглядеть как:
{Status:'Ok',Rows:{Row1:{},...}}
- Rows - массив записей.
В случае, если данные не найдены ответ будет следующим:
{Status:'Empty'}
Обращение к службе WhoIs
Имя модуля | /API/WhoIs | |
Параметры | ||
DomainName | Доменное имя | Строка |
DomainZone | Имя доменной зоны | Строка |
В случае не доступности сервера WhoIs ответ будет выглядеть как:
{Status:'Fail'}
В случае, если домен занят ответ будет выглядеть как:
{Status:'Borrowed',[...]}
- [...] - совокупность дополнительных параметров: именные сервера, дата окончания и т.д.
В случае, если домен свободен ответ будет выглядеть как:
{Status:'Free'}
Заказ хостинга
Имя модуля | /API/HostingOrder | |
Параметры | ||
ContractID | Идентификатор договора клиента | Число |
Domain | Полное доменое имя, включая доменную зону | Строка |
HostingSchemeID | Идентификатор тарифа на хостинг | Число |
DomainTypeID | Тип домена | Строка
|
[1]DomainName | Доменное имя | Строка |
[1]DomainSchemeID | Идентифитор тарифа на домен | Число |
[1] - параметр обязателен только в случае, если DomainTypeID равен Order или Transfer.
Заказ домена
Имя модуля | /API/DomainOrder | |
Параметры | ||
ContractID | Идентификатор договора клиента | Число |
DomainName | Доменное имя | Строка |
DomainSchemeID | Идентификатор тарифа на домены | Строка |
[1]HostingOrderID | Идентификатор заказа хостинга | Число |
IsPrivateWhoIs | Скрыть данные в WhoIs | Логический |
Ns1Name | Имя первого сервера имен | Строка |
Ns1IP | IP адрес первого сервера имен | Строка |
Ns2Name | Имя второго сервера имен | Строка |
Ns2IP | IP адрес второго сервера имен | Строка |
[2]Ns3Name | Имя дополнительного сервера имен | Строка |
[2]Ns3IP | IP адрес дополнительного сервера имен | Строка |
[2]Ns4Name | Имя расширенного сервера имен | Строка |
[2]Ns4IP | IP расширенного первого сервера имен | Строка |
[1] - в случае, если параметр указан для домена будут установлены именные сервера, сервера на котором размещен данный заказ хостинга.
[2] - параметры являются не обязательными.