# ApiMethod ## Шаблон ApiMethod ```xml ``` ## Описание ApiMethod ```xml ``` ### Атрибуты ApiMethod #### Name Имя кастомного API-метода. Обязательный атрибут. Значение атрибута `Name` может быть любым, но уникальным среди всех описанных API-методов. #### Route Описывает конечную точку маршрута, по которому будет выполняться действие, описанное в ApiMethod. Обязательный атрибут. Значение атрибута `Route`: ожидается любое значение, допустимое в URL. Полный маршрут будет иметь вид http\://\:\/data\_api/{Route}, где \ и \ - IP-адрес и порт компьютера, на котором запущена серверная часть.\ Например, для Route="user\_list" URL будет иметь вид . #### Method Метод HTTP запроса. Обязательный атрибут. Ожидается один из вариантов: Get, Post, Put или Delete. Поле носит информативный характер. #### VersionCode Версия используемого кода. Обязательный атрибут. Ожидается положительное число больше нуля. По умолчанию равно текущей версии кода. Зарезервировано для разделения изменений кода и соблюдения обратной совместимости. ## Тэги, специфичные для ApiMethod ### Enabled Признак активности api-метода (только v3). Необязательный тэг. Ожидается логическое выражение, результат условия или константа. Если тэг `` отсутствует, то используется значение True. Если значение тэга `` равно False, то в ответ на запрос сервер вернет статус 404 Not Found. ```xml True ``` ### Parameters Параметры, передаваемые в запрос. Необязательный тэг. В качестве значения тэга ожидается список тэгов [``](#parameters_parameter). ```xml ``` #### Тэг `` Параметр, который будет передан в команду при выполнении. Необязательный тэг. #### Атрибуты тэга ``
Name

Название параметра, по которому будет доступен в команде.

Обязательный атрибут.

Type

Тип значения передаваемого в параметре.

Обязательный атрибут. Ожидается одно из значений:

  • Integer
  • Decimal
  • DateTime
  • String
  • File
  • Boolean
  • Json
Source

Источник в HTTP-запросе для получения значения параметра.

Обязательный атрибут. Ожидается одно из значений:

  • FromQuery - возвращает значения из строки запроса
  • FormData - multipart/form-data
  • FromBody - возвращает значения из текста запроса
  • FromHeader - возвращает значения из заголовков HTTP
RequiredПризнак, обязательный параметр или нет.

Необязательный атрибут. Ожидается логическое значение.

По умолчанию атрибут имеет значение True.
{% hint style="warning" %} 1\. Для `FromBody` есть ограничение на обработку параметров относительно уровня вложенности объектов. В качестве параметров запроса можем указывать только поля основного объекта, которые принимают значение простых типов (строка, число, дата, логическое) и массив простых типов. Например, для объекта ```json { "id" : 1, "title" : "qwerty", "object" : { "field1" : "value1", "field2" : "value2" } } ``` мы укажем параметры "id"(Integer), "title"(String), но не можем указать параметры для "field1" и "field2". В этом случае мы должны указать параметр "object" с типом String. И вручную разбирать строку как json-объкт. PostgreSQL это позволяет. 2\. Type="Array" будет возвращать массив строк. {% endhint %} ### Commands Команды, выполняемые последовательно. Необязательный тэг. Полностью соответствует команде SequentialCommand на серверной части. Во всех командах доступны все параметры описанные в тэге [``](#parameters). ```xml ``` ### Response Описывает дополнительные поля в ответе на запрос. Необязательный тэг. Значение тэга ``: список тэгов [``](#response_objects) и [``](#response_relations). Если тэг `` не указан, то по умолчанию в json-объекте будут поля "result\_code" и "error", если при выполнении запроса возникли ошибки. ```xml ``` #### Тэг `` Описывает дополнительные поля в ответе на запрос. Необязательный тэг. Значение тэга ``: список тэгов [``](#response_objects_object). #### Тэг `` Дополнительное поле в ответе на запрос. Необязательный тэг. В качестве значения тэга `` ожидается тэг `` - обращение к команде. При этом если команда не выполнялась ранее, то она будет выполнена, иначе будет получено значение предыдущего выполнения. Так же можно обратится к конкретному параметру в результате команды по его имени через атрибут `Parameter`. #### Атрибуты тэга ``
Name

Название поля, которое будет указываться в json-объекте в ответе на запрос.

Обязательный атрибут.

Array

Будет ли поле представлено как массив или скалярное значение.

Необязательный атрибут. Ожидается логическое значение.

По умолчанию используется значение False. Если указан тэг <Relation> с именем этого объекта, то значение атрибута игнорируется и берется значение True.

#### Тэг `` Описывает отношение дополнительных полей между собой. Для указания вложенных объектов. Если не указан, то все таблицы - как самостоятельные поля json. Необязательный тэг. Значение тэга ``: список тэгов [``](#response_relations_relation). {% hint style="warning" %} Необходимо соблюдать порядок объявления тэгов `` для объектов с большой вложенностью: описываем каждый уровень последовательно, начиная с верхнего уровня, и проходя дерево в глубину. {% endhint %} #### Тэг `` Внешний ключ, по которому будет строиться зависимость вложенных объектов. Необязательный тэг. Значение тэга ``: не ожидается. #### Атрибуты тэга ``
ChildObject

Подчинённый объект.

Обязательный атрибут. Ожидается имя одного из Object.

ChildFieldСсылающееся поле.

Обязательный атрибут. Ожидается название поля подчинённого объекта.
ParentObject

Главный объект.

Обязательный атрибут. Ожидается имя одного из Object.

ParentFieldЦелевое поле.

Обязательный атрибут. Ожидается название поля главного объекта.
{% hint style="info" %} Возможные ситуации с тэгом ``: 1. Указан неверный `ChildField` или `ParentField` - при выполнении запроса вывалится ошибка KeyNotFoundException. 2. Указан неверный `ChildObject` или `ParentObject` - при выполнении запроса такой Relation будет игнорироваться. 3. В качестве `ChildObject` и `ParentObject` указан один и тот же объект - выкинет ошибку при старте сервера. {% endhint %} ## Примеры ### Простой пример на получение списка пользователей URL запроса . ```xml ``` UserListSelectSqlQueryCommand - SqlQueryCommand с текстом select запроса на получения списка. В качестве ответа будет получен json объект вида: ```json { "result_code": 0, "users": [ { "user_name": "user2", "user_title": "Администратор" }, { "user_name": "user", "user_title": "Разработчики" } ] } ``` ### Пример обновления записи в базе URL запроса . Тело запроса содержит объект: ```json { "id":66, "date":"2019-12-08 07:00:00Z", "reason_id":1, "comment":"комментарий" } ``` ```xml ``` ShiftInspectionUpdateSqlQueryCommand содержит запрос вида: ```sql UPDATE carrent.inspection SET date = {date}::timestamp, reason_shift_id = {reason_id}, comment = {comment} WHERE inspection_id = {id}; ``` В качестве ответа вернется стандартный объект: ```json { "result_code": 0 } ``` ### Пример построения вложенных объектов URL запроса . ```xml ``` InspectionSelectSqlQueryCommand и DamageListSelectSqlQueryCommand - select запросы на получение списка записей для user\_id = 41. Вариант ответа: ```json { "result_code": 0, "inspections": [ { "inspection_id": 11, "type": "inspection_pickup", "damages": [ { "damage_id": 13, "description": "царапина" }, { "damage_id": 14, "description": "вмятина" } ] }, { "inspection_id": 12, "type": "inspection_pickup", "damages": [ { "damage_id": 23, "description": "царапина" }, { "damage_id": 41, "description": "вмятина" } ] } ] } ``` Если бы в примере не был указан тэг ``, то ответ имел бы вид: ```json { "result_code": 0, "inspection": [ { "inspection_id": 11, "type": "inspection_pickup" }, { "inspection_id": 12, "type": "inspection_pickup" } ], "damages": [ { "damage_id": 13, "description": "царапина" }, { "damage_id": 14, "description": "вмятина" }, { "damage_id": 23, "description": "царапина" }, { "damage_id": 41, "description": "вмятина" } ] } ``` ### Пример передачи массива объектов в качестве параметра в теле запроса URL запроса . Тело запроса: ```json { "cars": [ { "title":"car1", "number":"num_1" }, { "title":"car2", "number":"num_2" }, { "title":"car3", "number":"num_3" }, { "title":"car4", "number":"num_4" } ] } ``` ```xml ``` Команда TestSqlQueryCommand содержит примерный код запроса: ```sql SELECT cars ->> 'title' AS title, cars ->> 'number' AS number FROM( SELECT unnest({cars}::json[]) AS cars ) T ``` После замены параметра будет иметь вид: ```sql SELECT cars ->> 'title' AS title, cars ->> 'number' AS number FROM( SELECT unnest(ARRAY[ '{"title": "car1","number": "num_1"}', '{"title": "car2","number": "num_2"}', '{"title": "car3","number": "num_3"}', '{"title": "car4","number": "num_4"}' ]::json[]) AS cars ) T ``` ### Примеры обработки результатов кастомных команд #### DataTable 1. ```xml ``` Вернёт первый элемент таблицы: ```json { "result_code": 0, "inspections": { "inspection_id": 56, "state": "new", "client": "Алёшин Пётр Алексеевич" } } ``` 2. ```xml ``` Вернёт значение поля "client" для первого элемента таблицы: ```json { "result_code": 0, "inspections": "Алёшин Пётр Алексеевич" } ``` 3. ```xml ``` Вернёт массив всех строк таблицы: ```json { "result_code": 0, "inspections": [ { "inspection_id": 56, "state": "new", "client": "Алёшин Пётр Алексеевич" }, { "inspection_id": 53, "state": "new", "client": "Иванов Иван Иванович" }, { "inspection_id": 51, "state": "new", "client": "Сидоров Олег Петрович" } ] } ``` 4. ```xml ``` Вернёт массив значений поля "client" для всех строк таблицы: ```json { "result_code": 0, "inspections": [ "Алёшин Пётр Алексеевич", "Крутиков Сергей Владимирович", "Сидоров Петр Викторович" ] } ``` #### List\ OR object\[] 1. ```xml ``` Вернёт первый элемент списка/массива: ```json { "result_code": 0, "inspections": "Алёшин Пётр Алексеевич" } ``` 2. ```xml ``` Вернёт массив всех значений списка/массива: ```json { "result_code": 0, "inspections": [ "Алёшин Пётр Алексеевич", "Крутиков Сергей Владимирович", "Сидоров Петр Викторович" ] } ``` #### Dictionary\ 1. ```xml ``` Вернёт первый элемент словаря: ```json { "result_code": 0, "inspection": { "inspection_id": 56, "state": "new" } } ``` 2. ```xml ``` Вернёт массив всех значений словаря: ```json { "result_code": 0, "inspections": [ { "inspection_id": 56, "state": "new" } ] } ``` 3. ```xml ``` Вернёт: ```json { "result_code": 0, "inspections": "Алёшин Пётр Алексеевич" } ``` 4. ```xml ``` Вернёт: ```json { "result_code": 0, "inspections": [ "Алёшин Пётр Алексеевич" ] } ``` #### List\> 1. ```xml ``` Вернёт: ```json { "result_code": 0, "inspections": { "inspection_id": 56, "state": "new" } } ``` 2. ```xml ``` Вернёт: ```json { "result_code": 0, "inspections": [ { "inspection_id": 56, "client": "Алёшин Пётр Алексеевич", "state": "new" }, { "inspection_id": 53, "client": "Крутиков Сергей Владимирович", "state": "new" }, { "inspection_id": 51, "client": "Сидоров Петр Викторович", "state": "new" } ] } ``` 3. ```xml ``` Вернёт: ```json { "result_code": 0, "inspections": "Алёшин Пётр Алексеевич" } ``` 4. ```xml ``` Вернёт: ```json { "result_code": 0, "inspections": [ "Алёшин Пётр Алексеевич", "Крутиков Сергей Владимирович", "Сидоров Петр Викторович" ] } ``` #### Dictionary\>> В процессе доработки! ```xml ``` добавить поддержку Array ```json { "result_code": 0, "inspections": [ { "inspection_id": 56, "state": "new" }, { "inspection_id": 53, "state": "new" }, { "inspection_id": 51, "state": "new" } ], "damages": [ { "damage_id": 17, "inspection_id": 56, "open_description": "test 1" }, { "damage_id": 18, "inspection_id": 51, "open_description": "test 2" } ] } ```