REST-сервис на основе OpenAPI (YAML/JSON)

На платформе Entaxy вы можете создать два типа сервисов: SOAP-сервис на основе WSDL и REST-сервис на основе OpenAPI (YAML/JSON). Выбор между ними зависит от требований проекта и предпочтений в использовании соответствующих технологий.

Ниже представлено руководство по созданию REST-сервиса, соответствующего принципам архитектуры REST и использующего спецификацию OpenAPI в форматах YAML или JSON.

Настройка пула потоков Jetty XML

Когда мы запускаем сервис в рабочей среде, мы можем настроить условия обработки запросов на стороне Jetty.

Для этого в файл jetty.xml (расположенный в ${karaf.etc}) внутрь тега:
<Configure id="Server" class="org.eclipse.jetty.server.Server"> добавьте следующие параметры:

<Get name="threadPool">
<Set name="minThreads">10</Set>
<Set name="maxThreads">1000</Set>
</Get>

Где:

maxThreads/minThreads — максимальное/минимальное количество потоков, которые Jetty может создавать и использовать в пуле.

Загрузка и управление файлами OpenAPI (YAML/JSON)

Для создания сервиса требуется файл в формате YAML/JSON с описанием API с использованием версии спецификации OpenAPI 3.0.1. Вы можете использовать редактор Swagger (https://editor.swagger.io/) для удобного создания и редактирования спецификации OpenAPI.

В спецификации OpenAPI (Swagger) используются зарезервированные ключевые слова:

("object", "list", "file", "localVarPath", "localVarQueryParams", "localVarCollectionQueryParams", "localVarHeaderParams", "localVarCookieParams", "localVarFormParams", "localVarPostBody", "localVarAccepts", "localVarAccept", "localVarContentTypes", "localVarContentType", "localVarAuthNames", "localReturnType", "ApiClient", "ApiException", "ApiResponse", "Configuration", "StringUtil", "abstract", "continue", "for", "new", "switch", "assert", "default", "if", "package", "synchronized", "boolean", "do", "goto", "private", "this", "break", "double", "implements", "protected", "throw", "byte", "else", "import", "public", "throws", "case", "enum", "instanceof", "return", "transient", "catch", "extends", "int", "short", "try", "char", "final", "interface", "static", "void", "class", "finally", "long", "strictfp", "volatile", "const", "float", "native", "super", "while", "null").

Если вам в API-схеме необходимо использовать какое-либо из этих слов, обратите внимание, что в Swagger UI оно будет автоматически переименовано для соответствия стандартам OpenAPI. Переименование отразится только в интерфейсе Swagger UI и не приведет к функциональным изменениям в самом API.
Для формирования ответов с большими объемами данных в REST-сервисах рекомендуется использовать сохраненные FTL-шаблоны, а не вписывать текст непосредственно в маршрут.

Подробнее о создании REST-сервиса на основе OpenAPI вы можете прочитать здесь. Его необходимо загрузить в подраздел schemas раздела Ресурсы. Подробнее о ресурсах вы можете прочитать здесь.

resources schemas empty

Чтобы загрузить созданный .yaml / .json файл на платформу, выполните следующие шаги:

Имя загружаемого файла не должно содержать пробелов.

  1. В навигационном меню найдите раздел Ресурсы.

  2. В разделе Ресурсы найдите подраздел schemas и перейдите на вкладку Resources.

  3. Для загрузки YAML/JSON файла вы можете выбрать один из следующих способов:

    1. Использовать кнопку "Upload resource" (Загрузить ресурс).

    2. Нажать правой кнопкой мыши для вызова контекстного меню и выбрать Upload.

      upload schema

  4. После загрузки появится подтверждающее сообщение о том, что файл успешно загружен: "File <file_name> was successfully uploaded."

  5. Ваш YAML/JSON файл будет сохранен в подразделе schemas.
    Вы можете использовать его для создания сервисов.

    files schemas rest

Характеристики YAML/JSON

Загрузив YAML/JSON-файл на платформу вы можете перейти на вкладку "openapi", для просмотра информации о сервисе.

json info

Поддерживаемые типы OpenAPI-based REST сервисов

rest service create

  1. SERVICE :: REST :: OPENAPI :: PROTECTED (защищенный REST-сервис)

    При создании защищенного сервиса требуется подключение входного коннектора.

    При создании REST-сервиса в режиме PROTECTED автоматически создается соответствующий входной коннектор, обеспечивающий безопасное взаимодействие с сервисом.

    При удалении защищенного REST-сервиса необходимо учесть - если входной коннектор уже был добавлен к профилю для корректного удаления сервиса необходимо сначала удалить коннектор.
    connector rest

  2. SERVICE :: REST :: OPENAPI :: PUBLIC (публичный REST-сервис)

    При создании публичного сервиса подключение входного коннектора не требуется, взаимодействие с шиной происходит с использованием кастомного маршрута, создаваемого при заведении сервиса.

Параметры REST-сервиса (protected/public)

emptyrestgeneral

General

Параметр Описание

*Factory

Идентификатор используемой фабрики. Обязательный параметр с предустановленным значением - REST :: OPENAPI :: PUBLIC

*Object Id

Уникальный идентификатор сервиса, может содержать только латинские буквы, цифры и дефис, и должно начинаться с буквы. Минимальная длина - 3 символа.

Display Name

Отображаемое имя сервиса. Необязательное поле.

Description

Краткое описание сервиса.
rest properties redelivery

Redelivery policy

Настройка обработки ошибок и повторной доставки сообщений. Подробнее ознакомиться можно здесь.

rest properties routes
addroute

Routes

  • AGGREGATOR
    Маршрут для агрегирования нескольких сообщений на основе заданных критериев.

  • LISTENER-QUEUE-ARTEMIS
    Маршрут для интеграции с использованием очередей брокера сообщений ActiveMQ Artemis, с прослушиванием и обработкой сообщений в рамках интеграционных маршрутов.

  • QUARTZ
    Маршрут используется для планирования задач с помощью Quartz Scheduler. Он позволяет запускать маршруты на основе расписания, которое можно настроить с помощью Cron выражений или простых интервалов времени.

  • ROUTE-CALLABLE
    Маршрут для выполнения настраиваемых логик и операций, позволяющий вызывать различные функции и взаимодействовать с внешними системами.

  • SUBSCRIPTION-TOPIC-ARTEMIS
    Маршрут для интеграции с использованием подписки на топики брокера сообщений ActiveMQ Artemis, с прослушиванием и обработкой сообщений в рамках интеграционных маршрутов.

  • TIMER
    Маршрут предназначен для создания периодических событий. Он позволяет запускать маршруты через заданные интервалы времени, такие как каждая секунда, минута или час, без необходимости использования внешних планировщиков или триггеров.

emptyrestmain

Main

Параметр Описание

Generating logging key (чек-бокс)

Активируйте этот параметр, чтобы автоматически создавать ключ для логирования, который будет использоваться для отслеживания процесса обработки запросов.

Remove all headers before answering

Удаление всех заголовков перед ответом.

Schema Validation Enabled (чек-бокс)

Активация проверки тела запроса на соответствие структуре и формату заданной схемы API.

Data Format (POJO/ORIGIN)

Формат представления данных:

* POJO: Используется для работы с данными в виде Plain Old Java Objects, что позволяет напрямую работать с Java объектами.

* ORIGIN: Используется для работы с данными в их исходном виде.

Выбор формата представления данных.

*Address

Адрес публикации сервиса в рамках шины. Указывает, по какому адресу сервис будет доступен для взаимодействия с другими компонентами системы. Если поле не заполнять, оно будет сгенерировано автоматически на основе Service Id (идентификатор сервиса).

*OpenAPI schema

Загрузка YAML/JSON файла. Для загрузки нажать "Select" и выбрать предварительно загруженный на платформу YAML/JSON файл. В открывшемся окне выбрать .yaml / .json файл и нажать кнопку "Select".

Title

Заголовок API. Заполняется автоматически на основе загруженного YAML/JSON файла.

*Operation Router

Редактируемый параметр маршрутизации данных на основе загруженного YAML/JSON файла.
security service

Security

  1. Authorization Type: JAAS

    Подробнее про JAAS.
    Подробнее про создание пользователей, ролей и групп.

    emptyrestsecurity
    Параметр Описание

    *Authorization realm

    Определяет реалм авторизации для сервиса, связывая его с соответствующими настройками безопасности.

    *Public Service Schema

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

    *Restrict access by roles

    Чек-бокс, позволяющий ограничивать доступ к сервису на основе ролей.

    *Roles allowed to access

    Перечень ролей, которым разрешен доступ к сервису.

  2. OAUTH STAND ALONE

    Метод авторизации, использующий OAuth 2.0 в автономном режиме без необходимости интеграции с другими системами для проверки токенов и управления доступом.
    oauthstandalone

    Параметр

    Описание

    *Public Service Schema

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

    *Restrict access by roles

    Чек-бокс, позволяющий ограничивать доступ к сервису на основе ролей.

    *Roles allowed to access

    Перечисляет роли, которые имеют доступ к сервису.

    *Regexp for jwt auth filter

    Регулярное выражение для фильтрации JWT токенов.
    Помогает в проверке и фильтрации входящих JWT токенов по заданным шаблонам.
    По умолчанию указано значение \W+ (любой неалфавитно-цифровой символ).

    *Keystore

    Поле предназначено для выбора файла .jks или .jwk, содержащего параметры подписи JWT.

    *Jwt Alias

    Название используемого alias для JWT.

    Пример настройки и валидации JWK/JKS keystore с Oauth Stand Alone с использованием REST API.

  3. OAUTH INTROSPECT

    Метод авторизации, использующий OAuth 2.0 для проверки состояния токенов доступа через introspection endpoint. Аутентификация клиента для доступа к introspection endpoint осуществляется с помощью client_id и client_secret.
    oauthintrospect

    Параметр

    Описание

    *Public Service Schema

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

    *Introspect Authorization Login

    Логин для авторизации (client_id);

    *Introspect Authorization Password

    Пароль для аутентификации при запросе проверки токена.
    По умолчанию задан параметр $ENTAXY_SECRETS{password@for-service}, где for-service — это название хранилища секретов в системе Vaults, а password — это alias в указанном хранилище, содержащий пароль.

    *Introspect URL

    URL-адрес для запроса информации о токене, который позволяет проверить его валидность и получить данные о нем.

    *Http receive timeout

    Максимальное время ожидания для получения ответа от сервера при запросе информации о токене. Значение по умолчанию - 60 секунд.

    Пример настройки и валидации OAuth Introspect с использованием REST API.

    См. также подробное описание Безопасность.

Создать сервис

  1. Для создания REST-сервиса перейдите в раздел Сервисы и Клиенты, затем откройте вкладку Services and Clients и нажмите на кнопку "Add Service".

    service navigation

  2. Вам будет предложено выбрать тип REST-сервиса: защищенный (protected) или публичный (public). Выберите нужный и нажмите кнопку "Next".

  3. В открывшемся окне вы увидите перечень параметров. Параметры REST-сервиса (protected/public) Заполните обязательные параметры и нажмите кнопку "Add".

    create rest protected general
    create rest protected main
    create rest protected security

  4. После выполнения этих действий сервис будет успешно создан.

    create rest protected done

Выбор формата представления данных

При создании REST-сервиса можно выбрать один из двух форматов представления данных: POJO или ORIGIN.

  • POJO (по умолчанию). В этом режиме данные автоматически преобразуются в Java-объект согласно описанию используемой схемы. Для обращения к полям объекта в языке Simple используются конструкции:

    • Стандартное поле:

      ${body.fieldName}

    • Если объект реализован через additionalProperties:

      ${body.get('fieldName')}

      Для обхода массива объектов рекомендуется использовать EIP Loop:

      <loop>
	<simple>${body.size()}</simple>
	<setProperty name="curObj">
		<simple>${body.get(${exchangeProperty.CamelLoopIndex})}</simple>
	</setProperty>
	<m:log message="GET field: ${exchangeProperty.curObj.fieldName}" />
	<m:log message="GET additionalProperties: ${exchangeProperty.curObj.get('fieldName')}" />
</loop>

      При необходимости можно вручную сериализовать объект с помощью компонента marshal. Пример с использованием библиотеки Jackson:

      <marshal>
<json library="Jackson"/>
</marshal>

      Также поддерживается библиотека Gson.

  • ORIGIN. Формат ORIGIN используется для передачи данных в исходном виде, без преобразования в Java-объекты. Тело сообщения при этом сериализуется в правильный JSON, и можно использовать JSONPath для обращения к полям и элементам данных.

Просмотреть список созданных сервисов

  • Перейдите в раздел Сервисы и Клиенты, затем откройте вкладку Services and Clients.

  • На этой вкладке вы увидите таблицу с информацией о созданных сервисах.

Таблица содержит следующие столбцы:

  • Name: уникальное имя созданного сервиса.

  • Status: текущий статус сервиса. Например, "Active" или "Resolved".

  • Actions: содержит кнопки для управления сервисом: Start (запуск сервиса), Stop (остановка сервиса), Edit (редактирование свойств сервиса).

    • View Properties: просмотр свойств сервиса.

    • Uninstall: удаление сервиса.

      service rest actions

Если вы хотите найти конкретный сервис по имени или статусу, используйте фильтр. Введите имя сервиса или выберите нужный статус в соответствующем поле фильтра. Таблица автоматически обновится, чтобы показать только результаты соответствующие поиску.

Остановить сервис

  1. На вкладке "Services and Clients" в строке соответствующего сервиса найдите столбец "Actions", в котором находятся кнопки управления сервисом.

  2. Нажмите кнопку Stop.

  3. Сервис будет остановлен. Появится подтверждающее сообщение о том, что операция выполнена успешно: "Operation Succeeded!".

  4. В столбце "Status" сервиса должно отображаться "Resolved", подтверждая успешную остановку.

    stop rest

Запустить сервис

  1. На вкладке Services and Clients в строке соответствующего сервиса найдите столбец "Actions", в котором находятся кнопки управления сервисом.

  2. Нажмите кнопку Start.

  3. Сервис будет запущен. Появится подтверждающее сообщение о том, что операция выполнена успешно: "Operation Succeeded!".

  4. В столбце "Status" сервиса должно отображаться "Active", подтверждая успешный запуск.

    start rest

Удалить сервис

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

  1. На вкладке Services and Clients в строке соответствующего сервиса найдите столбец "Actions", в котором находятся кнопки управления сервисом.

  2. Нажмите кнопку Uninstall.

  3. Появится сообщение с просьбой подтвердить удаление сервиса. Убедитесь, что вы действительно хотите удалить сервис, так как эту операцию нельзя отменить.

  4. Подтвердите удаление, выбрав Confirm или отмените удаление, выбрав Cancel.

  5. В случае подтверждения появится подтверждающее сообщение о том, что операция выполнена успешно: "Operation Succeeded!".

  6. Сервис удален. Он больше не будет отображаться в списке сервисов.

    uninstall rest