Материал из Joonte Wiki
Версия от 21:04, 10 ноября 2009; Бреславский Антон (обсуждение | вклад)

(разн.) ← Предыдущая | Текущая версия (разн.) | Следующая → (разн.)
Перейти к: навигация, поиск
Ключевые слова: 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
Параметры
Email Электронный адрес пользователя Строка
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
Параметры
Email Электронный адрес пользователя Строка
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 Тип домена Строка
  • Order - заказать домен
  • Transfer - перенести домен
  • None - ничего не делать
[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] - параметры являются не обязательными.