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

Учебные пособия API Manager

Создание и публикация GraphQL API

Запуск сервера бэкенда GraphQL

Мы будем использовать демонстрационный сервер Star Wars в качестве бэкенда для нашего GraphQL API.

  1. Скопируйте архив примеров NEOMSA APIM , после чего извлеките содержимое архива.

    wget https://nexus.do.neoflex.ru/repository/neomsa-isp/neomsa-apim/samples-neomsa-apim.zip
unzip samples-neomsa-apim.zip

  2. Перейдите в каталог graphql-backend.

    cd samples-apim-master/graphql-backend

  3. Запустите npm install для установки необходимых зависимостей node.

  4. Запустите npm start, чтобы запустить сервер.

После выполнения вышеуказанных шагов сервер Star Wars будет запущен на http://localhost:8080.

Можно использовать http://localhost:8080/graphql в качестве эндпоинта при создании API GraphQL.

Проектирование GraphQL API

  1. Войдите на портал издателя API.

https://<hostname>:9443/publisher

Пример: https://localhost:9443/publisher

Используйте admin в качестве логина и пароля для входа.

  1. Нажмите «Создать API», а затем нажмите «Импорт GraphQL SDL».

  1. Импортируйте схему. Перетяните файл схемы или загрузите его, затем нажмите "Далее".

Используем StarWarsAPI schema definition для создания файла схемы.

Примечание

  1. Введите данные, связанные с GraphQL API, и нажмите «Создать».

  2. Создайте API под названием «StarWarsAPI», используя следующий пример данных.

Поле Описание
Имя StarWarsAPI
Контекст /swapi
Версия 1.0.0
Конечная точка http://localhost:8080/graphql
Примечание:
При указании HTTP URL в качестве эндпоинта бэкенда NEOMSA APIM автоматически преобразует его в соответствующий WebSocket URL ws://localhost:8080/graphql.
После этого шлюз API будет использовать этот URL-адрес WebSocket в качестве эндпоинта подписки на бэкенд

  1. При желании можно изменить существующее описание схемы GraphQL.

    • Перейдите в раздел Разработка, Конфигурации API и нажмите Определение схемы.

    • Нажмите «Скачать определение».

Загружается существующая схема GraphQL API.

- При необходимости обновите определение схемы.

- Нажмите «Импортировать определение», чтобы импортировать обновленное описание схемы.
  1. При необходимости обновите операции GraphQL API.

Вместо ресурсов, которые заполняются для API REST, для API GraphQL заполняются следующие операции.

а. Нажмите «Показать больше» в разделе «Операции» на странице «Обзор», чтобы перейти на страницу операций.

1. При необходимости обновите операции.

Издатель может добавлять политики ограничения частоты запросов, области и включать/отключать безопасность для каждой из операций GraphQL API.

    1. Создание областей действия.

Повторите следующие шаги, чтобы создать две области с именами adminScope и FilmSubscriberScope.

        1. Нажмите Локальные области, а затем нажмите Создать области.


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

Примечание: Роль, которую вы вводите, должна быть допустимой ролью, которая уже существует в NEOMSA APIM . Обязательно назначьте роль пользователю.

Введите следующие данные для этого примера сценария.

Имя Роль
FilmSubscriber FilmSubscriber
adminScope admin 

        1. Нажмите, Enter чтобы добавить каждую роль.

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


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

        1. Нажмите «Операции».

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


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

Примените следующие области действия к соответствующим операциям.

Операция Скоуп
allDroids FilmSubscriber
allCharacters adminScope 
        1. Нажмите «Сохранить».

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

Итак, вы успешно создали и настроили GraphQL API.

Развертывание GraphQL API

  1. Перейдите в раздел «Развертывание» и нажмите «Развертывания», чтобы перейти на страницу «Развертывание API».

  2. Нажмите кнопку «Развернуть» , чтобы развернуть API на шлюзе API, который является шлюзом по умолчанию.

Откроется страница развертывания.

Публикация GraphQL API

  1. Перейдите в раздел «Опубликовать» и нажмите «Жизненный цикл».

Откроется страница жизненного цикла API.

  1. Нажмите «Опубликовать(Publish)», чтобы опубликовать API на портале разработчиков API.

Вызов GraphQL API

  1. Войдите на портал разработчиков.

https://<hostname>:9443/devportal

Пример: https://localhost:9443/devportal

Используем admin в качестве логина и пароля для входа.

  1. Нажмите на GraphQL API.

Появится обзор API.

Информация

- Обратите внимание, что в GraphQL API отображаются как HTTP, так и WebSocket-адреса шлюза.

- URL-адрес HTTP-шлюза предназначен для вызова операций запроса и мутации GraphQL API.

- URL-адрес шлюза WebSocket предназначен для вызова операций подписки GraphQL API.

  1. Подпишитесь на API.

    • Нажмите Проверка.

Это создаст подписку для приложения с именем DefaultApplication и сгенерирует пару ключа потребителя и секрета для DefaultApplication. Нажмите Проверка во всплывающем окне, чтобы перейти к Проверка.

  1. Попробуйте выполнить операции.

    • Нажмите кнопку ПОЛУЧИТЬ ТЕСТОВЫЙ КЛЮЧ .

Опционально попробуйте выполнить операцию запроса (Query)

Примечание

  • Если вы собираетесь вызвать QUERY операцию, начните запрос с ключевого слова «query».

  • Если вы собираетесь вызвать операцию MUTATION, начните запрос с ключевого слова «mutation».

  • Введите следующий пример в качестве запроса StarWarsAPI. Затем нажмите кнопку «Выполнить».

    query testQuery{
   human(id:1000){
      id
      name
   }
   droid(id:2000){
      name
      friends{
          name
          appearsIn
      }
   }
}

  1. Нажмите «Execute».

Опционально попробуйте выполнить операцию подписки (Subscription)

Примечание

Если вы собираетесь вызвать операцию SUBSCRIPTION, вам следует начать запрос с ключевого слова subscription.

  1. Введите следующий пример в качестве reviewAdded запроса на подписку StarWarsAPI, чтобы получать обновления в режиме реального времени о добавлении новых отзывов.

    subscription testSubscription{
   reviewAdded(episode: JEDI) {
      stars
      episode

      commentary
   }
}

  2. Подготовьтесь к инспектированию сетевых запросов с помощью инструментов разработчика вашего браузера.

Например, для браузера Google Chrome.

1. Щелкните правой кнопкой мыши по браузеру и выберите «Проверить».

1. Нажмите «Сеть», чтобы просмотреть сетевые вызовы с помощью инструментов разработчика браузера.
  1. Нажмите «Execute» .

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

Как вы можете видеть, между клиентом и бэкендом установлено успешное соединение WebSocket через NEOMSA APIM Gateway.

  1. Не закрывая страницу веб-браузера портала разработчика, откройте отдельный терминал и напрямую вызовите операцию изменения API бэкенда, createReview выполнив следующую команду:

    curl -X POST "http://localhost:8080/graphql" -H  "accept: application/json" -H  "Content-Type: application/json" -d '{"query":"mutation {createReview(episode: JEDI, review: { stars: 3, commentary: \"Excellent\"}) { stars   episode   commentary }}","variables":null}' -k

Если изменение прошло успешно, бэкенд GraphQL отправит следующий ответ:

{"data":{"createReview":{"stars":3,"episode":"JEDI","commentary":"Excellent"}}}
  1. Теперь вернитесь на страницу браузера портала разработчиков.

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

Поиск неисправностей

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

Это приведет к выводу следующей ошибки в бэкенде.

ERROR - InboundWebsocketSourceHandler Endpoint not found for port : 8099 tenant domain : null

Чтобы решить эту проблему, откройте соответствующий эндпоинт HTTPS эндпоинта WSS непосредственно из браузера и подтвердите сертификат безопасности. (например, https://localhost:8099/swapi/1.0.0)

Если у API Manager есть сертификат, подписанный центром сертификации (CA), эндпоинты WSS должны работать сразу после установки.

Вы успешно создали и опубликовали свой первый API GraphQL, подписались на него, получили токен доступа для тестирования и протестировали операции запросов и подписок вашего API с токеном доступа

Представление SOAP-сервиса в виде REST API

NEOMSA APIM поддерживает управление существующими сервисами на основе SOAP и WSDL, которые представляются как REST API. Организации, имеющие сервисы на основе SOAP/WSDL, могут легко перенести свои существующие сервисы на REST без затрат на масштабную миграцию. NEOMSA APIM поддерживает два вида сервисов: один для выполнения «сквозной передачи» сообщения SOAP на бэкенд, а другой создает RESTful API из SOAP- сервиса.

В этом руководстве мы рассмотрим шаги по проектированию, публикации и вызову службы SOAP как RESTful API с использованием Pass Through.

Проектирование SOAP-сервиса как REST API

  1. Войдите в API Publisher и нажмите Create API. Выберите «Импортировать WSDL»

  1. Выберите опцию «Пропуск», а затем один из следующих вариантов:

    • URL-адрес WSDL. Если вы выберете этот вариант, вам необходимо указать URL-адрес эндпоинта.

    • WSDL-архив/файл - если вы выбрали этот параметр, нажмите «Обзор» и загрузите либо отдельный файл WSDL, либо архив WSDL, который представляет собой проект WSDL, содержащий несколько WSDL.

Примечание: При загрузке архива WSDL все зависимые файлы WSDL/XSD, на которые ссылается родительский WSDL файл, должны находиться внутри самого архива WSDL. В противном случае в процессе создания API произойдёт ошибка валидации.

В качестве примера здесь используется WSDL по адресу: http://users.bugred.ru/tasks/soap/WrapperSoapServer.php?wsdl , но можно использовать любой SOAP на ваш выбор.

  1. Нажмите кнопку Next, чтобы перейти к следующему этапу, введите информацию в таблицу ниже и нажмите кнопку Create.
Поле Пример значения
Имя PhoneVerification
Контекст /phoneverify
Версия 1.0
Конечная точка http://ws.cdyne.com/phoneverify/phoneverify.asmx

  1. Созданный API отображается в издателе следующим образом.

  1. Определение API созданной схемы отображается на вкладке «Определение API».

Примечание

Если вы хотите добавить области действия к созданным ресурсам, перейдите в раздел Ресурсы и разверните ресурсы. После этого создайте новые области действия и укажите их в области operation scope. Если вы указываете область действия, вам необходимо использовать ту же область действия при генерации токенов доступа для подписанного приложения вызова API.

Примечание

Обратите внимание, что при создании этого API, параметр по умолчанию Rate limiting level был выбран на API Level.

  1. Перейдите в Жизненный цикл и нажмите кнопку Опубликовать. Теперь вы опубликовали SOAP API на портале разработчиков.

Вызов службы SOAP как REST API

  1. Войдите на портал разработчиков, перейдите на вкладку «Подписки» и подпишитесь на API, используя (например, DefaultApplication).

  1. Нажмите кнопку Управление приложением при появлении запроса Просмотреть учетные данные.

  1. Нажмите Генерировать токен доступа , после чего появится всплывающее окно с предложением создать токен доступа к приложению.

  1. Нажмите Генерировать .

Сгенерированный JSON Web Token (JWT) появится во всплывающем окне. Обязательно

скопируйте его.

Сделаем вызов API.

  1. Перейдите на вкладку Проверка и вставьте токен в поле ввода токена доступа.

  1. Разверните метод POST и нажмите Try it out. Введите следующее и нажмите Execute , чтобы вызвать API.
SOAP-запрос <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<CheckPhoneNumber xmlns="http://ws.cdyne.com/PhoneVerify/query">
<PhoneNumber>18006785432</PhoneNumber>
<LicenseKey>18006785432</LicenseKey>
</CheckPhoneNumber>
</soap:Body>
</soap:Envelope>
Действие SOAP http://ws.cdyne.com/PhoneVerify/query/CheckPhoneNumber

  1. Обратите внимание на ответ API, который появляется на консоли.

Примечание

Вы также можете вызвать этот API с помощью стороннего инструмента, такого как SOAP UI.

Создание и публикация WebSocket API

Это руководство поможет вам создать приложение чата на основе WebSocket с помощью NEOMSA APIM . Следуйте инструкциям в этом руководстве, чтобы спроектировать и опубликовать API через WebSocket, а затем вызвать API WebSocket с помощью клиента WebSocket wscat.

Вы получите простую чат-комнату на основе командной строки, с двумя каналами: rooms и notifications.

Примечание

При создании WebSocket Streaming API он предоставляется через оба протокола ws и wss. По умолчанию ws протокол использует порт 9099, а wss протокол использует порт 8099.

Проектирование WebSocket API

  1. Войдите в систему издателя.

https://<hostname>:9443/publisher

Для тестирования используйте https://localhost:9443/publisher введите admin в качестве логина и пароля.

  1. Нажмите «Создать API», перейдите в раздел «Потоковый API» и нажмите «WebSocket API».

Примечание

Кнопка «Создать» появится только для пользователя, имеющего разрешение на эту роль: creator.

  1. Введите данные нового WebSocket API.
Поле Пример значения
Name Chats
Context /chats
Version 1.0.0
Protocol WebSocket
Endpoint ws://localhost:8080

Примечание

- Когда вы создаете API WebSocket Streaming, он предоставляется через протоколы ws и wss. По умолчанию протокол ws использует порт 9099, а протокол wss использует порт 8099.

- Для незащищенных WebSockets введите протокол, как ws:// в эндпоинте, для защищенных WebSockets введите протокол, как wss://
  1. Нажмите Создать.

Появится страница обзора созданного WebSocket API.

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

    • Нажмите «Время выполнения» в разделе «API Configurations», выберите требуемый тип аутентификации и нажмите «Save».

  1. Добавьте темы в WebSocket API.

    • Нажмите на «Ресурсы» и перейдите на страницу «Ресурсы».

    • Удалите существующую тему по умолчанию с именем /*.

    • Добавьте следующие темы по одной.

Выберите типы: pub и sub, введите название топика и нажмите +, чтобы добавить каждую тему.

  • /notifications

  • /rooms/{roomID}

- Разверните каждую тему, укажите сопоставление URL-адресов следующим образом и нажмите «Сохранить».
Тема URL-маппинг
/notifications /notifications
/rooms/{roomID} /rooms?room={uri.var.roomID}

Маппинг URL, предоставленный для темы, будет добавлен к URL адресу эндпоинта WebSocket который был указан при создании API, а трафик через эту тему будет отправляться и получать данные через полученный URL.

  1. Прикрепите бизнес-планы к вашему WebSocket API.

    • Нажмите «Подписки» и перейдите на страницу «Бизнес-планы».

    • Выберите AsyncGold и нажмите кнопку «Сохранить».

Теперь вы успешно создали и настроили WebSocket API.

Публикация API WebSocket

  1. Нажмите «Жизненный цикл», чтобы перейти к жизненному циклу API, и нажмите «Publish», чтобы опубликовать API на портале разработчиков API.

  2. Нажмите «Развертывания», чтобы перейти на страницу «Развертывания», и нажмите «Развернуть новую версию».

  3. Выберите Production и Sandbox, выберите localhost в окне VHost и нажмите Развернуть.

Запуск сервера WebSocket

  1. Загрузите пример сервера WebSocket из архива примеров NEOMSA APIM , после чего извлеките содержимое архива.

    wget https://nexus.do.neoflex.ru/repository/neomsa-isp/neomsa-apim/samples-neomsa-apim.zip
unzip samples-neomsa-apim.zip

  2. Перейдите в каталог: streaming-api-backends/websocket-backend и установите необходимые зависимости.

    npm install

  3. Запустите сервер.

    npm start

Вызов WebSocket API

  1. Войдите на портал разработчиков.

https://<hostname>:9443/devportal

В целях тестирования можно использовать https://localhost:9443/devportal и admin в качестве логина и пароля.

  1. Нажмите на WebSocket API.

Появится обзор API.

  1. Подпишитесь на API.

    1. Нажмите «Подписки», чтобы перейти на страницу «Подписки», и нажмите на кнопку «Подписка» в области «Мастер создания подписок и ключей».

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

Примечание: Для подписки на API можно использовать любое приложение (например, JWT или OAuth).

1. Скопируйте появившийся токен авторизации и нажмите «Готово».

  1. Попробуйте выполнить операции.

    1. Установить клиент wscat.

      npm install -g wscat

    2. Вызовите тему API /notifications с помощью заголовка.

      Для WS-OAuth2
wscat -c ws://localhost:9099/chats/1.0.0/notifications -H "Authorization: Bearer [accesstoken]"

Для WSS-OAuth2
wscat -n -c wss://localhost:8099/chats/1.0.0/notifications -H "Authorization: Bearer [accesstoken]"

Для WS-API Key
wscat -c ws://localhost:9099/chats/1.0.0/notifications -H "apikey: [API_key_value]"

Для WSS-API-Key
wscat -n -c wss://localhost:8099/chats/1.0.0/notifications -H "apikey: [API_key_value]"

При успешном подключении сервер WebSocket отправит сообщение:

Subscribed to notifications!

1. В отдельном терминале вызовите тему API /rooms/{roomID} указав заголовок, выполнив следующую команду.

    ```
    Для WS-OAuth2
    wscat -c ws://localhost:9099/chats/1.0.0/rooms/room1 -H "Authorization: Bearer [accesstoken]"

    Для WSS-OAuth2
    wscat -n -c wss://localhost:8099/chats/1.0.0/rooms/room1 -H "Authorization: Bearer [accesstoken]"

    Для WS-API Key
    wscat -c ws://localhost:9099/chats/1.0.0/rooms/room1 -H "apikey: [API_key_value]"

    Для WSS-API-Key
    wscat -n -c wss://localhost:8099/chats/1.0.0/rooms/room1 -H "apikey: [API_key_value]"
    ```

При успешном подключении сервер WebSocket отправит сообщение:

You joined room1!

Это означает, что первый пользователь подключился к room1.

Кроме того, в терминале, где вы вызвали тему /notifications, будет показано следующее сообщение. Оно означает уведомление о вышеуказанном событии.

Someone joined room1!

1. В другом терминале снова вызовите тему API /rooms/{roomID}. Это обозначает второго пользователя, который будет подключаться к room1.

    ```
    Для WS-OAuth2
    wscat -c ws://localhost:9099/chats/1.0.0/rooms/room1 -H "Authorization: Bearer [accesstoken]"

    Для WSS-OAuth2
    wscat -n -c wss://localhost:8099/chats/1.0.0/rooms/room1 -H "Authorization: Bearer [accesstoken]"

    Для WS-API Key
    wscat -c ws://localhost:9099/chats/1.0.0/rooms/room1 -H "apikey: [API_key_value]"

    Для WSS-API-Key
    wscat -n -c wss://localhost:8099/chats/1.0.0/rooms/room1 -H "apikey: [API_key_value]"
    ```

Вы получите сообщение: «You joined room1!» в этом терминале, вместе с соответствующим уведомлением в терминале notifications.

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

Примечание: Существуют клиенты (особенно браузеры), которые не позволяют добавлять заголовки в WebSocket handshake. В таких случаях можно отправить токен доступа или API-ключ для вызова WebSocket API в качестве параметра запроса, используя команды ниже:

Для WS-OAuth2
wscat -c "ws://localhost:9099/chats/1.0.0/notifications?access_token=[accesstoken]"

Для WSS-OAuth2
wscat -n -c "wss://localhost:8099/chats/1.0.0/notifications?access_token=[accesstoken]"

Для WS-API Key
wscat -c "ws://localhost:9099/chats/1.0.0/notifications?apikey=[API_key_value]"

Для WSS-API-Key
wscat -n -c "wss://localhost:8099/chats/1.0.0/notifications?apikey=[API_key_value]"

Примечание: BasicAuth не обеспечивают безопасность WebSocket API.

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

Создание и публикация WebSub/WebHook API

Это руководство поможет создать WebHook API, который будет отслеживать новые тикеты в GitHub и отправлять вам уведомления при их создании. Следуйте инструкциям, чтобы спроектировать, опубликовать WebSub/WebHook API и зарегистрировать для него WebHook.

В руководстве демонстрируется простой WebSub/WebHook API, который отслеживает ваш репозиторий GitHub на предмет новых тикетов (issues) и получает события при их создании.

Создание API WebSub/WebHook API

  1. Войдите в систему издателя.

https://<hostname>:9443/publisher

Для тестирования можно использовать https://localhost:9443/publisher, admin- в качестве логина и пароля.

  1. Нажмите «Создать API» , перейдите в раздел потоковой API нажмите API вебхук.

Примечание: Кнопка Create появится только для пользователей, имеющих разрешение на эту роль creator.

  1. Введите данные нового WebSub/WebHook API.
Поле Пример значения
Name RepoWatcher
Context /repo-watcher
Version 1.0.0
Protocol WebSub
  1. Нажмите Create.

Появится страница обзора созданного WebSub/WebHook API.

  1. Добавьте тему в WebSub/WebHook API.

    1. Нажмите «Темы» и перейдите на страницу «Темы».

    2. Нажмите «Добавить тему», добавьте тему с названием /issues, нажмите «Добавить» и нажмите «Сохранить».

  1. Сгенерируйте секрет.

    1. Разверните раздел «Subscription Configuration» на странице «Ресурсы».

1. Нажмите на переключатель «Включить», чтобы включить генерацию секрета.

1. Выберите SHA1 в качестве алгоритма подписи.

1. Нажмите «Generate», чтобы сгенерировать секрет.


1. Скопируйте сгенерированный секрет.

Назовем сгенерированный секрет [generated_secret].

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

  1. Прикрепите бизнес-планы к WebSub/WebHook API.

    1. Нажмите «Подписки» и перейдите на страницу «Бизнес-планы».

    2. Выберите AsyncWHGold и нажмите «Сохранить».

Теперь вы успешно создали и настроили WebSub API (WebHook API).

Перенаправление публичного URL-адреса

Публичный URL-адрес должен быть перенаправлен на localhost:9021, чтобы ваш локальный сервер мог быть доступен поставщику WebHook (GitHub). Для этой цели можно использовать ngrok.

  1. Загрузите ngrok и запустите его.

Это создаст перенаправление с публичного URL-адрес на localhost:9021.

./ngrok http 9021
  1. Скопируйте HTTP URL, который перенаправляется на http://localhost:9021, как показано в терминале ngrok.

Например это http://3b1*******c9.ngrok.io.

Forwarding                    http://3b1*******c9.ngrok.io -> http://localhost:9021
Forwarding                    https://3b1*******c9.ngrok.io -> http://localhost:9021

Добавление WebHook в собственный репозиторий GitHub

Примечание: Для этой цели вы можете использовать существующий репозиторий GitHub или создать новый.

  1. Перейдите в настройки вашего репозитория GitHub.

  2. Нажмите WebHooks , перейдите на страницу WebHooks и нажмите Add WebHook .

  1. Настройте WebHook.

    1. Вернитесь к NEONSA APIM, нажмите «Ресурсы», чтобы перейти на страницу «Ресурсы», и разверните тему /issues .

    2. Скопируйте URL обратного вызова.

      https://{GATEWAY_HOST}:9021/repo-watcher/1.0.0/webhooks_events_receiver_resource?topic=/issues

    3. Вернитесь на страницу WebHooks вашего репозитория GitHub .

Укажите следующие значения.

Поле Значение
Payload URL http://3b1*******c9.ngrok.io/repo-watcher/1.0.0/webhooks_events_receiver_resource?topic=/issues
Это достигается путем замены Ошибка! Недопустимый объект гиперссылки. части URL-адреса обратного вызова темы /issues на URL-адрес HTTP пересылки из ngrock (например)., http://3b1*******c9.ngrok.io).
Тип контента application/json
Секрет [generated_secret]
Это секрет, который вы получили из раздела «Конфигурация подписки» в темах API WebSub/WebHook.
Какие события должны вызывать этот WebHook? Выберите "Let me select individual events" и отметьте "Issues" 

1. Нажмите Добавить WebHook .

Публикация WebSub/WebHook API

  1. Перейдите к издателю NEOMSA APIM

  2. Нажмите «Жизненный цикл», чтобы перейти к жизненному циклу API.

  3. Нажмите ОПУБЛИКОВАТЬ, чтобы опубликовать API на портале разработчиков API.

  4. Нажмите «Развертывания», чтобы перейти на страницу «Развертывания».

  5. Нажмите «Развернуть новую ревизию».

  6. Выберите Production и Sandbox, выберите localhost в выпадающем меню VHost и нажмите Развернуть.

Создание URL-адреса обратного вызова

  1. Перейдите по адресу https://webhook.site/

  2. Нажмите «New», оставьте значения по умолчанию и нажмите «Create».

Для вас будет создан уникальный URL-адрес.

  1. Скопируйте в буфер обмена ваш уникальный URL-адрес.

  1. Закодируйте уникальный URL, который вы скопировали, с помощью URL-кодирования.

Назовем уникальный URL-адрес, закодированный в URL [encoded_hub_callback] .

  1. Оставьте веб-страницу открытой, так как вам придется вернуться к ней снова.

Вызов API WebSub/WebHook API

  1. Войдите на портал разработчиков.

https://<hostname>:9443/devportal

В целях тестирования можно использовать https://localhost:9443/devportal, admin в качестве логина и пароля.

  1. Нажмите на WebSub/WebHook API.

Появится обзор API.

  1. Подпишитесь на API.

    1. Нажмите «Подписки», чтобы перейти на страницу «Подписки», и нажмите «Мастер подписок и генерации ключей».

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

Примечание: Для подписки на API можно использовать любое приложение (например, JWT или OAuth).

1. Скопируйте появившийся токен авторизации и нажмите кнопку Готово.

  1. Попробуйте выполнить операции.

    1. Подпишитесь на тему (topic) /issues.

      1. Подпишитесь на URL обратного вызова с темой /issues, выполнив следующую команду cURL. Замените [encoded_hub_callback] и accesstoken на полученные вами значения.


curl -X POST 'http://localhost:8280/repo-watcher/1.0.0' -H 'Content-Type: application/x-www-form-urlencoded' -d 'hub.topic=%2Fissues' -d 'hub.callback=[encoded_hub_callback]' -d 'hub.mode=subscribe' -d 'hub.secret=newValue' -d 'hub.lease_seconds=50000000' -H 'Authorization: Bearer [accesstoken]'

    1. Нажмите «Подписки», чтобы перейти на страницу подписок вашего приложения на портале разработчиков.

    1. Нажмите на записи о подписке WebSub API. Появится список подписок, которые вы только что создали.

    1. Перейдите в свой репозиторий GitHub и создайте новый тикет. Это активирует созданный вами GitHub WebHook.

    1. Вернитесь на веб-страницу https://webhook.site/, где вы создали URL обратного вызова. Появился бы новый запрос, который обозначает создание проблемы.


1. Отписаться от темы /issues.

Отмените подписку на URL-адрес обратного вызова для темы /issues, выполнив следующую команду cURL.

Замените [encoded_hub_callback] и accesstoken полученными вами значениями.

curl -X POST 'http://localhost:8280/repo-watcher/1.0.0?hub.callback=[encoded_hub_callback]&hub.mode=unsubscribe&hub.secret=newValue&hub.lease_seconds=50000000&hub.topic=/issues' -H "Authorization: Bearer [accesstoken]"

Вы успешно создали и опубликовали свой первый WebSub/WebHook API, подписались на него, получили токен доступа для тестирования, создали подписку на WebHook и протестировали свой API с токеном доступа.

Примечание: NEOMSA APIM также поддерживает запросы на подписку с application/x-www-form-urlencoded типом контента, который соответствует стандартам, указанным W3C. Это позволяет передавать параметры центрального сервера (hub) в теле запроса в виде данных формы. API Manager также поддерживает возможность дополнительной проверки подписчиков, чтобы убедиться, что запрос действительно исходит от них, для этого типа запросов. Это можно включить, добавив свойство enableSubscriberVerification со значением, установленным true на портале издателя. Значение по умолчанию установлено на false. В более поздних версиях это можно напрямую включить, изменив конфигурации WebSub на панели конфигураций API.

Создание и публикация Server Sent Events (SSE) API

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

Проектирование SSE API

  1. Войдите в систему издателя.

https://<hostname>:9443/publisher

Для тестирования можно использовать https://localhost:9443/publisher и в качестве логина и пароля: admin.

  1. Нажмите Создать API, перейдите в раздел Потоковый API и нажмите SSE API.

Примечание: Кнопка Create появится только для пользователя, имеющего разрешение на эту роль: creator.

  1. Введите данные нового SSE API.
Поле Пример значения
Имя Observer
Контекст /observer
Версия 1.0.0
Протокол SSE
Конечная точка http://localhost:8080
  1. Нажмите Create.

Появится страница обзора созданного SSE API.

  1. Прикрепите бизнес-планы к API SSE.

    1. Нажмите «Подписки» и перейдите на страницу «Бизнес-планы».

    2. Выберите AsyncGold и нажмите «Сохранить».

Итак, вы успешно создали и настроили SSE API.

Публикация SSE API

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

  2. Нажмите «Publish», чтобы опубликовать API на портале разработчиков API.

  3. Нажмите «Развертывания», чтобы перейти на страницу «Развертывания», и нажмите «Развернуть новую версию».

  4. Выберите Default, нажмите Развертывать.

Запуск сервера SSE

  1. Загрузите пример сервера SSE из архива примеров NEOMSA APIM , после чего извлеките содержимое архива.

    wget https://nexus.do.neoflex.ru/repository/neomsa-isp/neomsa-apim/samples-neomsa-apim.zip
unzip samples-neomsa-apim.zip

  2. Перейдите в каталог streaming-api-backends/sse/target и выполните следующую команду.

    java -jar sse-server-1.0.0.jar --time=5000 --interval=1000

Вызов SSE API

  1. Войдите на портал разработчиков.

https://<hostname>:9443/devportal

Для тестирования можно использовать https://localhost:9443/devportal, admin в качестве логина и пароля.

  1. Нажмите на API SSE.

Появится обзор API.

  1. Подпишитесь на API.

    1. Нажмите «Подписки», чтобы перейти на страницу «Подписки», и нажмите «Мастер подписок и генерации ключей».

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

Примечание: Для подписки на API можно использовать любое приложение (например, JWT или OAuth).

1. Скопируйте появившийся токен авторизации и нажмите кнопку Закрыть.

  1. Попробуйте выполнить операции.

Вызовите API с использованием заголовка авторизации, выполнив следующую команду cURL.

curl http://localhost:8280/observer/1.0.0/memory -H "Authorization: Bearer [accesstoken]"

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

data:{"heap":67893392,"nonHeap":36260800,"ts":1614803952066,"identifier":"ram_222"}

data:{"heap":72591160,"nonHeap":37250808,"ts":1614803953067,"identifier":"ram_223"}

data:{"heap":72591160,"nonHeap":37251544,"ts":1614803954064,"identifier":"ram_224"}

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

Редактирование API путем изменения его определения через Swagger

NEOMSA APIM имеет интегрированный редактор Swagger, который является частью проекта Swagger.

Swagger— это полностью открытая, стандартная, не зависящая от языка спецификация и полноценная структура для описания, создания, потребления и визуализации RESTful API без необходимости использования прокси-сервера или сторонних сервисов. Swagger позволяет пользователям понять возможности удаленного сервиса даже если у них нет доступа к исходному коду, и взаимодействовать с этой службой с минимальными усилиями. Swagger помогает описать сервис так же, как интерфейсы описывают низкоуровневый программный код.

Swagger Editor— это независимая коллекция HTML, JavaScript и CSS, которая динамически генерирует документацию из API, совместимого со Swagger. API, совместимые со Swagger, предоставляют интерактивную документацию, возможность генерации клиентских SDK и улучшенную доступность. Swagger Editor позволяет работать с кодом в формате JSON, облегчает форматирование, выделяет ключевые слова и показывает синтаксические ошибки в реальном времени. Вы можете добавлять параметры ресурсов, краткие описания и подробные пояснения к свои API с помощью Swagger Editor.

NEOMSA APIM поддерживает спецификации Open API 3.1.0, Open API 3.0 и Open API 2.0, и вы можете легко создавать, импортировать, редактировать и использовать API, в этих форматах.

В этом руководстве рассмотрим, как добавить интерактивную документацию к API, непосредственно редактируя код Swagger через интерфейс API Publisher.

Примечание: В этом руководстве используется PizzaShackAPI.

  1. Войдите в API Publisher и выберите разработку нового REST API. https://<hostname>:9443/publisher

  1. Нажмите «Создать новый REST API».

  2. На странице «Создание API» укажите имя API, контекст, версию и эндпоинт как показано ниже, затем нажмите «Создать».

Поле Пример значения
Name PizzaShack
Version 1.0.0
Context /pizzashack
Endpoint https://localhost:9443/am/sample/pizzashack/v1/api/
Добавляемая вами конечная точка автоматически добавляется в виде production и sandbox endpoints.

Будет отображен интерфейс обзора созданного API.

  1. Нажмите на Определение API в боковом меню, чтобы просмотреть определение API в графическом интерфейсе Swagger. Откроется Swagger UI.

  1. Добавьте методы GET и PUT для API.

    1. Под объектом paths удалите {} и добавьте следующий код, как показано на скриншоте ниже.

Примечание: В коде ниже обратите внимание, что у вас есть ресурс, определенный с шаблоном URL /order/{orderId}под объектом paths. За ним следуют методы HTTP GET и PUT. Для каждого метода HTTP определены следующие параметры.

- responses: Объект для хранения ответов, которые могут использоваться в операциях. Подробности см. в спецификации Swagger.

- x-auth-type: специфичный для NEOMSA APIM объект для определения типа аутентификации метода.

- x-throttling-tier: специфичный для NEOMSA APIM объект, который определяет уровень ограничения пропускной способности (throttling tier) метода.

    ```
    /order/{orderId}:
        get:
          description: Get details of an Order
          parameters:
          - name: orderId
            in: path
            description: Order Id
            required: true
            schema:
              type: string
              format: string
          responses:
            200:
              description: OK Requested Order will be returned
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/Order'
          security:
          - default: []
          x-auth-type: Application & Application User
          x-throttling-tier: Unlimited
      put:
          description: Update an existing Order
          parameters:
          - name: orderId
            in: path
            description: Order Id
            required: true
            schema:
              type: string
              format: string
          requestBody:
            description: Order object that needs to be added
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Order'
            required: true
          responses:
            200:
              description: OK. Successful response with updated Order
              headers:
                Location:
                  description: The URL of the newly created resource.
                  schema:
                    type: string
                Content-Type:
                  description: The content type of the body.
                  schema:
                    type: string
              content:
                application/json:
                  schema:
                $ref: '#/components/schemas/Order'
            security:
              -
                default: []
            x-auth-type: "Application & Application User"
            x-throttling-tier: "Unlimited"
    ```

  1. Определите схему Order. Добавьте следующий код в определение API ниже раздела Paths.

    definitions:
       Order:
      required:
        - "orderId"
      properties:
        customerName:
          type: "string"
        delivered:
          type: "boolean"
        address:
          type: "string"
        pizzaType:
          type: "string"
        creditCardNumber:
          type: "string"
        quantity:
          type: "number"
        orderId:
          type: "string"
      title: "Pizza Order"

Примечание: Метод PUT имеет параметр пути, определенный со ссылкой на схему «Order».

parameters:
        -
        name: "orderId"
        in: "path"
        description: "Order Id"
        required: true
        type: "string"
        format: "string"
        -
        in: "body"
        name: "body"
        description: "Order object that needs to be added"
        required: true
        schema:
            $ref: "#/definitions/Order"

1. Нажмите Обновить содержимое. Это добавит ресурс с двумя методами HTTP в API, который будет виден на вкладке Ресурсы издателя API вместе с определенными параметрами.

Предположим, что бэкенд этого API отправляет ответ в формате XML. Задокументируем это в методе GET в ресурсе, который мы только что добавили.

Информация: Если после добавления определения API в Swagger UI вы столкнулись с ошибкой, сначала проверьте правильность отступов в коде. Swagger требует точного соблюдения отступов, и выдает ошибки, если отступы не были соблюдены.

  1. Добавьте краткое описание метода GET.

    1. Нажмите «Edit Source» и добавьте следующий код, который задает краткое описание (summary) и подробное описание (description), к методу GET.

      summary: "Get Order details"
description: "Get details of an order by order Id"


1. Нажмите Apply Changes. Краткое и подробное описание метода GET, который вы добавили, видны при раскрытии метода GET в API Publisher.

  1. Измените название API.

    1. Нажмите Edit Source и добавьте следующий код в Swagger UI. Это заголовок, который видят потребители на Developer Portal после публикации API.

      info:
    title: PizzaShackAPI

Вы можете увидеть, как это изменение отражается на портале разработчиков на шаге 12.

1. Нажмите «Применить изменения» и завершите процесс создания API.

  1. Завершите оставшуюся часть процесса создания API. Для получения дополнительной информации см. шаг 7 и далее в разделе Создание REST API

  2. Нажмите «Просмотр» на портале разработчиков, и появится API, который вы только что опубликовали.

  3. Нажмите Try Out. Обратите внимание, что изменения, которые вы внесли ранее, теперь отображаются на портале разработчиков для потребителей.

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

Примечание: Записи, связанные с расширением вендора (такие как x-auth-type и x-throttling-tier), нельзя изменять напрямую через редактор Swagger, поскольку они тесно интегрированы с внутренними функциями NEOMSA