Интерфейс взаимодействия с сервером приложений Archimedes посредством передачи JSON сообщений

Contents

Интерфейс взаимодействия с сервером приложений Archimedes посредством передачи JSON сообщений
1. JSON запросы
2. JSON ответы
  1. Исключения
  2. Ответы сервера

Сервер обрабатывает входящий HTTP PUT или POST запрос, содержащий JSON сообщение в кодировке UTF-8. Ответом является JSON сообщение в кодировке UTF-8.

JSON запросы

JSON запрос - это массив из одного и более типизированных запросов к серверу. На каждый типизированный запрос сервер отвечает либо исключением (исключения), либо ответом (возможные ответы).

   1 [
   2   request1,
   3   request2,
   4   request3,
   5   ...
   6 ]

при этом каждый запрос обязан содержать следующие атрибуты:

Название	Тип атрибута	Описание
type	string	Тип запроса
requestID	string	Идентификатор запроса

Запрос авторизации

Пример:

   1 {
   2   "type": "authorization",
   3   "requestID": "1",
   4   "login": "andrey",
   5   "password", "passW0RD"
   6 }

Название	Тип атрибута	Описание
login	string	Логин пользователя
password	string	Пароль пользователя

Перечень ответов:

Запрос на зачитывание таблицы

Пример:

   1 {
   2   "type":"table",
   3   "key": "2be6e6ad1552a3726ba0ba8f55b874ee",
   4   "requestID": "2",
   5   "name": "ContactPerson",
   6   "columns": [
   7                {"name": "lastName"},
   8                {"name": "firstName"},
   9                {"name": "phone"}
  10              ],
  11   "startRow": 0,
  12   "count": 10,
  13   "parameters": {
  14                   "keys": [
  15                             {
  16                               "field": "contactTypeID",
  17                               "id": 1082,
  18                               "class": "ContactType"
  19                             }
  20                           ],
  21                   "sort": [
  22                             {
  23                               "field": "lastName",
  24                               "direction": 1
  25                             },
  26                             {
  27                               "field": "firstName",
  28                               "direction": -1
  29                             }
  30                           ],
  31                   "filters": [
  32                                {
  33                                  "field": "lastName",
  34                                  "regex": "И.*"
  35                                }
  36                              ]
  37                 }
  38 }

Название	Тип атрибута	Описание
key	string	Ключ авторизации
name	string	Название класса объектов бизнес-логики, для которых зачитывается таблица
columns	список колонок	Перечень атрибутов объектов, которые необходимо получить
startRow	int	Начальная строка таблицы для загрузки
count	int	Количество записей (-1 если все)
parameters	параметры таблицы	Перечень параметров, таких как родительские ключи, сортировка, фильтры

Перечень ответов:

список колонок

Список колонок представляет массив описаний колонок, которые необходимо получить с сервера

Пример описания колонок:

   1 [
   2   {"name": "lastName"},
   3   {"name": "firstName"},
   4   {"name": "phone"}
   5 ]

Название	Тип атрибута	Описание
name	string	Название колонки (имя атрибута объекта бизнес логики)

параметры таблицы

параметры таблицы влючают: keys - список родительских ключей, sort - колонки для сортировки, filters - фильтры по колонкам

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

   1 {
   2   "keys": [
   3             {
   4               "field": "contactTypeID",
   5               "id": 1082,
   6               "class": "ContactType"
   7             }
   8           ],
   9   "sort": [
  10             {
  11               "field": "lastName",
  12               "direction": 1
  13             },
  14             {
  15               "field": "firstName",
  16               "direction": -1
  17             }
  18           ],
  19   "filters": [
  20                {
  21                  "field": "lastName",
  22                  "regex": "И.*"
  23                }
  24              ]
  25 }

keys

Список родительских ключей применяется в том случае, когда нужно для определенного объекта системы (например организации) получить список дочерних объектов (например, сотрудников). Для получения сотрудников организации с id = 1082 параметр keys может выглять следующим образом:

   1 "keys": [
   2           {
   3             "field": "organizationID",
   4             "id": 1082,
   5             "class": "Organization"
   6           }
   7         ]

Название	Тип атрибута	Описание
field	string	Имя атрибута объекта, ссылающегося на родительский объект
id	int	Идентификатор родительского объекта
class	string	Имя класса родительского объекта

sort

Список полей для сортировки

Название	Тип атрибута	Описание
field	string	Имя колонки (атрибута объекта) по которому нужно выполнить сортировку
direction	int	Направление сортировка (1 - по возрастанию, -1 - по убыванию)

filters

Список фильтров по колонкам

Название	Тип атрибута	Описание
field	string	Имя колонки (атрибута объекта) по которому нужно отфильтровать записи
regex	string	Регулярное выражение, описывающее фильтр

Запрос на создание новой записи

Пример запроса

   1 {
   2   "type": "create",
   3   "key": "53890e95a8835dcf9e2a4615556d9e3e",
   4   "requestID": "3",
   5   "name": "Currency"
   6 }

Название	Тип атрибута	Описание
name	string	Название класса объекта который нужно создать
parameters	параметры таблицы	Перечень параметров таблицы, из которой создается новая запись

Перечень ответов:

Запрос на открытие записи

Пример запроса

   1 {
   2   "type": "open",
   3   "key": "53890e95a8835dcf9e2a4615556d9e3e",
   4   "requestID": "4",
   5   "name": "Currency",
   6   "id": 3909
   7 }

Название	Тип атрибута	Описание
name	string	Название класса объекта который нужно получить
id	int	Идентификатор объекта
parameters	параметры таблицы	Перечень параметров таблицы, из которой открывается запись

Перечень ответов:

Запрос на сохранение записи

Пример запроса

   1 {
   2   "type": "save",
   3   "key": "53890e95a8835dcf9e2a4615556d9e3e",
   4   "requestID": "5",
   5   "name": "Currency",
   6   "object": {
   7     "id": 3909,
   8     "attributes": {
   9        "name": {"value" : "Рубль"},
  10        "shortName": {"value":"RUR"}
  11     }
  12   }
  13 }

Название	Тип атрибута	Описание
name	string	Название класса объекта который нужно сохранить
parameters	параметры таблицы	Перечень параметров таблицы, из которой была открыта сохраняемая запись
object	передаваемый объект	Данные объекта, который нужно сохранить

Перечень ответов:

передаваемый объект

Передаваемый объект содержит идентификатор объекта и значение атрибутов для передачи на сервер

Пример:

   1 {
   2   "id": 3909,
   3   "attributes": {
   4     "name": {"value" : "Рубль"},
   5     "shortName": {"value":"RUR"}
   6   }
   7 }

Название	Тип атрибута	Описание
id	int	Идентификатор объекта
attributes	object	Значение атрибутов объекта (ассоциативный массив, ключ - имя поля объекта, значение - значения атрибута объекта)

значения атрибута объекта

Значение атрибутов объекта

Название	Тип атрибута	Описание
value	string	Текстовое значение атрибута (используется для все типов кроме ссылки)
id	int	Идентификатор объекта, на который ссылается ссылочное поле

Запрос на вызов метода

Пример запроса

   1 {
   2   "type": "invoke",
   3   "key": "53890e95a8835dcf9e2a4615556d9e3e",
   4   "requestID": "6",
   5   "name": "Currency",
   6   "method": "__save__",
   7   "object": {
   8     "id": 3909,
   9     "attributes": {
  10        "name": {"value" : "Рубль"},
  11        "shortName": {"value":"RUR"}
  12     }
  13   }
  14 }

Название	Тип атрибута	Описание
name	string	Название класса объекта для которого вызывается метод
method	string	Имя метода
parameters	параметры таблицы	Перечень параметров таблицы, из которой была открыта запись для которой вызывается метод
object	передаваемый объект	Данные объекта, для которого нужно вызвать метод

Перечень ответов:

Запрос на удаление записей

Пример запроса

   1 {
   2   "type": "delete",
   3   "key": "53890e95a8835dcf9e2a4615556d9e3e",
   4   "requestID": "7",
   5   "name": "Currency",
   6   "ids": [ 3909 ]
   7 }

Название	Тип атрибута	Описание
name	string	Название класса объектов которые необходимо удалить
parameters	параметры таблицы	Перечень параметров таблицы, из которой была открыта запись для которой вызывается метод
ids	массив идентификаторов	Массив идентификаторов объектов, которые нужно удалить

Перечень ответов:

JSON ответы

JSON ответ - это массив из одного и более типизированных ответов сервера

   1 [
   2   response1,
   3   response2,
   4   response3,
   5   ...
   6 ]

при этом каждый ответ обязан содержать следующие атрибуты:

Название	Тип атрибута	Описание
requestID	string	Идентификатор запроса, которому соответствует данный ответ
exception	boolean	Флаг, что ответ является исключением
type	string	Тип ответа

Исключения

Каждое исключение сервера имеет следующий вид:

Пример:

   1 {
   2   "requestID" : "1",
   3   "type" : "security",
   4   "exception" : true,
   5   "message" : "Введен неверный логин или пароль!",
   6   "details" : ""
   7 }

Название	Тип атрибута	Описание
type	string	Тип исключения
message	string	Сообщение об ошибке
details	string	Дополнительные сведения об ошибке

Исключения могут быть следующих типов:

server - сообщение об ошибке, связанное с невозможностью совершить стандартное действие (например, DELETE) для объекта системы
security - возникает в случаях когда пользователь не проходит авторизацию (например при логине или при доступе к определенным объектам системы)
business - возникает в случаях когда пользователь совершает действие, которое не разрешено в рамках бизнес-процесса (например, "Необходимо выберать продукт или услугу, прежде чем создавать счет!")
database - исключение соответствует необработанной ошибке базы данных||

Ответы сервера

Ответ на успешную авторизацию

Пример:

   1 {
   2   "config" : "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<config>\n</config>\n",
   3   "exception" : false,
   4   "key" : "2be6e6ad1552a3726ba0ba8f55b874ee",
   5   "requestID" : "1",
   6   "type" : "login",
   7   "uri" : "Archimedes.CRM.UserConnection.3768"
   8 }

Название	Тип атрибута	Описание
key	string	Ключ авторизации. Данный ключ должен передаваться в последующих запросах для авторизации
uri	string	URI в ActiveMQ сервере, предназначен для получения асинхронных запросов с сервера (пока не используется)
config	string	XML, содержащий конфигурационные настройки, полученные с сервера

Ответ на запрос зачитывания таблицы

Пример:

   1 {
   2    "count" : 1,
   3    "exception" : false,
   4    "header" : [
   5       {
   6          "name" : "id",
   7          "type" : ""
   8       },
   9       {
  10          "name" : "name",
  11          "type" : ""
  12       }
  13    ],
  14    "name" : "Currency",
  15    "requestID" : "2",
  16    "rows" : [
  17       {
  18          "access" : 15,
  19          "id" : 3914,
  20          "values" : [
  21             "id" : {
  22                "access" : 3,
  23                "value" : "3914"
  24             },
  25             "name" : {
  26                "access" : 3,
  27                "value" : "USD"
  28             }
  29          ]
  30       }
  31    ],
  32    "startRow" : 0,
  33    "type" : "table",
  34    "version" : 669876569
  35 }

Название	Тип атрибута	Описание
count	int	Количество записей в ответе
header	описание колонок	Описание колонок таблицы
name	string	Имя класса возвращаемых объектов
rows	данные таблицы	Данные таблицы
startRow	int	Номер записи в таблице с которого начинаются данные таблицы
version	int	Версия таблицы - изменяется при изменении объекта, входящего в данную таблицу

описание колонок

Описание колонок - это массив колонок, каждая из которых содержит следующие данные:

Название	Тип атрибута	Описание
name	string	Имя колонки (атрибута класса)
type	string	Тип колонки (атрибута класса), не используется

данные таблицы

Данные таблца - это массив возвращаемых строк, начиная со строки с номером startRow и заканчивая строкой с номером startRow + count - 1 Каждый элемент массива сорежит объект:

объект

Пример объекта:

   1 {
   2   "access" : 15,
   3   "id" : 3909,
   4   "attributes" : {
   5     "comment" : {
   6       "access" : 3,
   7       "value" : ""
   8     },
   9     "id" : {
  10       "access" : 3,
  11       "value" : "3909"
  12     },
  13     "isBase" : {
  14       "access" : 3,
  15       "value" : "0"
  16     }
  17   }
  18 }

Название	Тип атрибута	Описание
access	int	Права пользователя на данную запись (бинарное разложение дает SELECT = 1, INSERT = 2, UPDATE = 4, DELETE = 8)
id	int	Идентификатор объекта, соответствующего записи
attributes	значения атрибутов	Ассоциативный массив (ключ - название атрибута)

значения атрибутов

Название	Тип атрибута	Описание
access	int	Права пользователя на атрибут объекта (бинарное разложение дает READ = 1, WRITE = 2)
id	int	Идентификатор объекта, на которое ссылается поле, используется для ссылочных полей
value	string	Текстовое значение поля

Получение объета

Пример:

   1 {
   2    "exception" : false,
   3    "object" : {
   4       "access" : 15,
   5       "attributes" : {
   6          "comment" : {
   7             "access" : 3,
   8             "value" : ""
   9          },
  10          "id" : {
  11             "access" : 3,
  12             "value" : "3909"
  13          },
  14          "isBase" : {
  15             "access" : 3,
  16             "value" : "0"
  17          }
  18       },
  19       "id" : 3909
  20    },
  21    "requestID" : "4",
  22    "type" : "record"
  23 }

Название	Тип атрибута	Описание
object	объект	Объект бизнес-логики

Перечень удаленных объектов

Пример:

   1 {
   2   "type" : "deleted",
   3   "requestID" : "7",
   4   "ids" : [ 3909 ]
   5 }