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

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

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

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

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

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

resources schemas empty

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

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

  2. Внутри раздела Ресурсы найдите подраздел Схемы (Schemas) и перейдите на вкладку Resources.

  3. Используйте окно открывшейся вкладки, чтобы переместить в него ваш YAML/JSON файл.

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

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

    files schemas rest

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

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

json info

Описание параметров:

  • Object:

    • info: объект содержит общую информацию о вашем API, такую как - заголовок (title) и версия (version);

    • operations: доступные операции/методы;

    • serviceResourcesRoot: корневой путь к ресурсам сервиса. Указанный путь находится в подразделе "service-resources";

    • Classes: информация о классах или сущностях используемых в API;

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

rest service create

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

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

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

    connector rest

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

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

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

emptyrestgeneral

  • Общие (general):

    Все параметры являются обязательными.

    • Factory Id: идентификатор фабрики создаваемого сервиса. Предустановлен.

    • Service Id: идентификатор сервиса (имя сервиса). Поле для назначения уникального имени создаваемому сервису. Системное имя может содержать только латинские буквы, цифры и дефис, и должно начинаться с буквы. Минимальная длина системного имени 3 символа.

    emptyrestmain

  • Основные (main):

    Все параметры являются обязательными, однако, при загрузке yaml/json-файла они будут автоматически заполнены значениями по умолчанию, при необходимости их можно отредактировать.

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

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

    • Public Service Schema: параметр, который позволяет сервису предоставить публичный доступ к своей схеме данных, даже если для доступа к остальным ресурсам требуется аутентификация.

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

    • Enable Authorization. Только для публичного REST-сервиса. Чек-бокс указывающий требуется ли авторизация для доступа к сервису.

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

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

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

    service navigation

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

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

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

    rest example

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

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

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

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

  • Name: отображает уникальные имена созданных сервисов.

  • Status: указывает текущий статус каждого сервиса, например, "Active" или "Resolved".

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

    • View Properties: кнопка для просмотра свойств выбранного сервиса.

    • Edit Properties: кнопка для редактирования свойств выбранного сервиса.

      list rest services

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

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

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

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

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

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

    stop rest

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

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

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

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

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

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

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

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

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

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

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

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