Перейти к содержанию

Создание API

REST API

Следуйте приведенным ниже инструкциям, чтобы создать REST API с помощью с помощью одного из основных сценариев:

  1. Войдите в систему NEOMSA APIM Publisher.

  1. Выберите REST API из предложенных вариантов.

  2. Нажмите «Создать API с нуля».

  1. Введите данные об API.

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

  1. Нажмите кнопку «Создать», чтобы создать API. Откроется страница обзора только что созданного API.

  1. Перейдите в раздел «Разработка», «Конфигурации портала» и нажмите «Основная информация».

а) настройте конфигурации проектирования API.

б) добавьте тег и нажмите клавишу «Ввод».

в) в качестве опции выберите «Да» для параметра «Сделать эту версию версией по умолчанию».

г) Нажмите «Сохранить».

  1. Настройте конфигурации среды выполнения.

а) нажмите кнопку «Среда выполнения», которая находится в разделе Конфигурации API.

б) Если вы хотите ограничить доступность API только одним из видов транспортного протокола (например, HTTPS), снимите флажок «Защита транспортного уровня».

По умолчанию выбраны оба транспортных протокола - HTTP и HTTPS.

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

  1. Настройте ресурсы.

По умолчанию в API будет пять ресурсов с /* в качестве шаблона URL.

8.1. Нажмите «Ресурсы», которые находятся в разделе «Конфигурации API».

8.2. Измените ресурсы необходимым образом и нажмите кнопку «Сохранить», чтобы обновить ресурсы.

8.2.1 Выберите подходящий HTTP-глагол из выпадающего списка и нажмите (+), чтобы добавить новый ресурс.

8.2.2 Разверните созданную операцию GET, чтобы добавить сведения для разделов «Краткое содержание и описание» и «Управление операцией».

8.2.2.1 Добавьте краткое описание ресурса.

8.2.2.2 При необходимости обновите настройки безопасности.

  • Отключите настройки безопасности, если вы хотите сделать определенную операцию API незащищенной и доступной без передачи токена доступа.

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

  • При необходимости добавьте параметры ресурса в разделе "Параметры".

Вы можете определить следующие типы параметров на основе параметров ресурсов, которые вы добавляете.

Тип параметра Описание
Запрос (query) Содержит поля, добавленные как часть URL-адреса вызова, который содержит данные, используемые для вызова бэкенд-сервиса.
Заголовок (header) Содержит чувствительные к регистру имена, за которыми следует двоеточие (:), а затем его значение, которое несет дополнительную информацию с запросом, определяющую рабочие параметры транзакции.
файл cookie Операции также могут передавать параметры в заголовке Cookie, как Cookie: name=value. Несколько параметров cookie передаются в одном заголовке, разделяясь точкой с запятой и пробелом.
Тело (body) В сообщении POST отправляется произвольный объем данных любого типа.
  1. В качестве дополнения можно просмотреть спецификацию API.

Нажмите кнопку «Описания API» (API Definition).

Появится спецификация OpenAPI (она же спецификация Swagger) для API PizzaShack.

Таким образом, вы успешно создали и настроили REST API. Далее следует развернуть API, протестировать его и, в завершение, опубликовать.

GraphQL API

При использовании GraphQL пользователи могут явно указать, какие данные им нужны от API. API на языке GraphQL являются альтернативой API на основе REST.

Для разработки GraphQL API в NEOMSA APIM можно использовать схему Schema Definition Language (SDL), аналогично созданию SOAP API с помощью WSDL и разработке REST API с помощью спецификаций OpenAPI (также известных как Swagger Definitions).

Все схемы GraphQL обычно имеют три корневых типа операций, а именно: запрос, мутация и подписка. Поэтому каждый запрос к конечной точке GraphQL-сервера должен иметь полезную нагрузку, начинающуюся с любого из корневых типов, включая имя соответствующей операции. Вы можете управлять безопасностью, авторизацией и ограничением количества запросов для каждой операции, основываясь на ее имени.

Примечание. клиент GraphQL поддерживает только протокол graphql-transport-ws, но шлюз поддерживает оба протокола - graphql-transport-ws и graphql-ws.

Для разработки GraphQL API на главной странице Publisher портала выберите «Создать API» (Create API), затем в выпадающем меню – GraphQL.

API обработки потоков данных (Streaming API)

Архитектура, основанная на событиях (Event Driven Architecture, EDA), позволяет немедленно передавать в приложения изменения данных и состояния, а также интересующие бизнес-события, не требуя от приложений выполнения опроса с целью получения обновлений. Организации используют EDA для того, чтобы улучшить свои приложения, обеспечив их удобство и интерактивность (например, мгновенное отображение изменений в котировках акций). В дополнение к EDA также необходимо управлять потоковыми API в сценариях, когда организации нужно представить свои потоки событий в управляемом виде, получать прибыль на основе потоковых данных или разрешить доступ к определенным API только авторизованным клиентам. Однако организации сталкиваются с множеством проблем, перечисленных ниже, когда пытаются реализовать событийно-ориентированную архитектуру или внедрить технологию обработки событий.

  • Интеграция существующих приложений с платформой событий.

  • Предоставление потоков событий веб-приложениям и внешним пользователям.

  • Новые приложения должны быть модифицированы для решения проблем транспортного уровня.

  • Интеграция постоянных хранилищ данных в потоковом режиме.

  • Обработка потоков событий.

Для решения перечисленных задач NEOMSA APIM предоставляет возможность работы с потоковыми API.

Принципы работы потокового API

Потоковый API – это логическая коллекция связанных тем, с помощью которых клиенты могут публиковать и получать события в четко определенном формате. Темы в потоковых API представляют собой различные каналы. Темы в потоковых API можно сравнить с ресурсами в REST API.

Тема (топик) позволяет выполнять следующие действия: «Подписаться» и/или «Опубликовать».

  • Подписаться – тема этого типа позволяет передавать трафик от сервера (бэкенда) к клиенту.

  • Опубликовать – тема этого типа позволяет передавать трафик от клиента к серверу.

NEOMSA APIM поддерживает потоковые API через следующие основные протоколы, совместимые с HTTP.

  • WebSocket

  • WebSub (WebHook)

  • Server Sent Events (SSE)

API WebSocket и SSE Streaming требуют постоянного соединения между клиентом и шлюзом API. Это позволяет серверу непрерывно транслировать события с паузами в середине, если это необходимо, через одно соединение, тем самым устраняя лишние затраты на создание новых соединений. Таким образом, протоколы WebSocket и SSE позволяют издателям поддерживать постоянные каналы связи с получателями. Однако потоковые API WebSub не требуют наличия постоянного соединения. Вместо этого WebSub API при необходимости выполняют HTTP-вызов.

Когда вы создаете WebSocket API, WebSub API/ WebHook API или SSE API, он связывает существующую реализацию потокового API с издателем API, чтобы вы могли управлять и контролировать жизненный цикл API, документацию, безопасность, сообщество и подписки.

Вы можете определять потоковые API с помощью определений AsyncAPI. Поэтому в качестве альтернативы вы можете создать потоковый API, который поддерживает любой из вышеперечисленных протоколов, используя определение AsyncAPI.

Для разработки потокового API в NEOMSA APIM выберите на главной странице «Создать API» (Create API), затем в выпадающем меню – потоковой API (Streaming API).

Создание API с помощью сервиса

Каталог сервисов в NEOMSA APIM содержит службы, которые соответствуют либо микроинтегратору (Micro Integrator), либо потоковому интегратору (Streaming Integrator). Службы Micro Integrator соответствуют внутренним службам REST API, а службы Streaming Integrator - внутренним службам Streaming API (т. е. WebSocket, WebHook/WebSub или SSE), которые управляются соответствующим уровнем интеграции (Micro Integrator или Streaming Integrator).

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

Для разработки API с помощью сервиса выберете на главной странице «Создать API» (Create API), затем в выпадающем меню – «Каталог сервисов».

Также вы можете перейти в раздел «Услуги» (Services) с главной страницы, выбрав соответствующий раздел в левой панели управления.

Выберите услугу в каталоге для просмотра подробной информации. Здесь отображается название сервиса, версия, описание, использование в API и другие важные метаданные.

AI API

API для ИИ обеспечивают бесшовную интеграцию сервисов ИИ в приложения. Используя функцию API для ИИ, вы можете выбрать конкретных поставщиков ИИ, которые наилучшим образом соответствуют вашим потребностям.

NEOMSA APIM обеспечивает встроенную поддержку ведущих провайдеров ИИ:

  • Anthropic;

  • AWS Bedrock;

  • Azure OpenAI;

  • Gemini;

  • Mistral AI;

  • OpenAI;

  • Azure AI Foundry.

Обратите внимание: помимо поставщиков по умолчанию, вы можете добавить собственных поставщиков ИИ, следуя инструкции по интеграции пользовательских поставщиков ИИ.

Чтобы создать API для искусственного интеллекта, выполните следующие действия:

1. **Создайте API для ИИ**:

  • Авторизуйтесь на портале издателя.

  • На странице просмотра списка API нажмите Create a new API, и затем на отобразившейся форме нажмите Create AI API.

  • Далее на форме создания выберите в выпадающих списках интересующего поставщика AI/LLM сервиса и версию API. Затем нажмите Далее.

  • В завершение укажите Name, Display Name, Context и Version для API ИИ.

Контекст API используется шлюзом для идентификации API. Следовательно, контекст API должен быть уникальным. Этот контекст является корневым контекстом API при вызове API через шлюз.

Вы можете определить версию API в качестве параметра его контекста, добавив его версию в контекст. Например, `{version}/openaiapi.`. Менеджер API присваивает параметру фактическую версию API. Например, `https://localhost:8243/2.3.0/openaiapi.`. Обратите внимание, что версия отображается перед контекстом, что позволяет группировать API на основе версий.

Когда сведения на форме будут указаны, нажмите Создать.

1. **Получите ключ API от поставщика услуг ИИ**:

  • В панели управления поставщика создайте новый секретный ключ, указав его имя и уровень прав доступа.

    1. Настройте тестовые и рабочие точки доступа:

  • На портале издателя NEOMSA APIM перейдите в Настройки API – Точки доступа.

  • Затем в блоке Default Production Endpoint нажмите и введите значение ключа API, полученное у поставщика услуг.

Подход к авторизации для каждого поставщика указан ниже:

- Anthropic: x-api-key header;

- AWSBedrock: Requires both an AWS Access Key and AWS Secret Key for authentication;

- AzureAIFoundry: api-key header;

- AzureOpenAI: api-key header;

- Gemini: X-goog-api-key header;

- MistralAI: Authorization header;

- OpenAI: Authorization header.

Обратите внимание: при взаимодействии с MistralAI и OpenAI необходимо добавить "Bearer" перед значением заголовка, поскольку они ожидают заголовок типа Authorization.

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

  • При необходимости аналогичным образом отредактируйте значения в блоке Sandbox Endpoint.

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

Для более подробного ознакомления с возможностями шлюза ИИ в API Manager обратитесь к разделу «AI Gateway».

Создание API с использованием Sequence в качестве бэкенда

При использовании последовательности в качестве бэкенда вы можете выполнять любую логику посредничества, которая выступает в качестве бэкенда для REST API . NEOMSA APIM интегрировал поддержку вызова REST API с пользовательской логикой посредничества через API Gateway. Выполните следующие шаги, чтобы создать и опубликовать API с последовательностью в качестве бэкенда.

Шаг 1 — Создание REST API

  1. Войдите в портал издателя API https://<hostname>:9443/publisher.

  2. Нажмите кнопку «Создать API» , а затем кнопку « Начать с нуля» .

  1. Введите данные API без указания URL-адреса конечной точки и нажмите «Создать» .

Шаг 2 — Добавление конечной точки бэкенда последовательности

  1. Нажмите «Конечные точки» , чтобы перейти на страницу «Конечные точки».

  2. Перейдите к типу «Конечная точка бэкенда последовательности» и нажмите «Добавить» .

Вы будете перенаправлены на страницу административной панели.

  1. Загрузите файл последовательности в выбранный тип ключа.

Для загрузки нажмите кнопку «Добавить» под выбранным типом ключа. Конфигурация конечной точки бэкенда Sequence должна содержать как минимум одну последовательность для API.

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

  1. Нажмите «Сохранить».

Здесь перечислены загруженные последовательности для предпочтительных типов ключей.

  1. Загрузить последовательность, загруженную пользователем, выбранного типа ключа. Это позволит загрузить последовательность, загруженную пользователем.

  2. Удаление последовательности, загруженной из предпочтительного типа ключа. Если удаляется только один элемент, операция будет недоступна, поскольку в качестве типа конечной точки "Sequence Backend" необходимо указать как минимум одну последовательность.

  3. Нажмите « Сохранить ».

Примечание: Кнопка не будет активирована, если в конфигурации конечной точки Sequence Backend не указана последовательность.

Примечание: Тип конечной точки Sequence Backend применим только для REST API и может быть развернут только в Synapse Gateway.