Павло Щербуха

Logo

Персональна освітня сорінка

Розробка на Node.js, VUE.js, Python, IBM Integration Bus (App Connect Ent) , ORACLE PL/SQL
15 November 2024

Learning IBM API-Connect

by Pavlo Shcherbukha

1. Постановка проблеми

Про продукт IBM API-Connect я чув давно, десь 3 2017-2018 року. Його характеризували як дуже гнучкий і зручний. Не зважаючи на гнучкість продукту я ні разу не пройшов весь процес його викристання. Але цього разу все ж таки пройшов більшість кроків, щоб надати “гнучкому” продукту “форму” і заставити його гнутися “як треба”, тобто пройти основні процеси (чи потоки) використання API-Connect. Для вивчення я використав хмарну версію цьго продукта, що була розгорнута в IBM Cloud. Здається, в рамках “IBM CloudPack for Integration” існує версія, що розгортається в OpenShift локального дата-центру, но це не точно. Тому всі мої досліди виконувалися в рамках IBM Cloud. Обговорювати які продукти є конкурентами IBM API-Connect я не хочу. Для цього можна покласти руку на клавіатуру і погуглити. Якщо шукати по youtube інформацію, як працювати з IBM API-Connect, то в більшості випадків це:

2. Про коцепцію продукта в моєму зрозумінні

Перш за все потрібно сказати кілька слів про концепцію продукта в моєму зрозумінні. IBM API-Connect призначений для того, щоб компанія, яка вирішила виставити свої Web Servise як API “в світ” мала можливість:

Тому, записав демонстраціцю роботи з IBM API Connect, що достпне за лінком: Демонстрація IBM API Connect. Розробку ж API винсі в окремий блог, тому що це найбільш складний етап.

Робота з API Connect починається з фази Розробки (Development), де визначаються дві сутності:

pic-01

На pic-02 показано головне вікно з каталогом API, що я створив в API-Connect.

pic-02

На pic-03 показано головне вікно з каталогом Products, що створив в API Connect.

pic-03

pic-04

Крім того продукт має свій життєвий цикл:

Після закінчення фази розробки настає наступна фаза Публікація продукту в каталог Catalog (або Catalogs).

На pic-05 показано створено каталог Catalogs та як в нього попасти

pic-05

А на pic-06 внутрішні сутності Catalog

pic-06

Створюється портал через Catalog так, як показано на pic-07:

pic-07

Основні елементи порталу, показані на pic-08

pic-08

Навіть зважаючи на наведене, можна зрозуміти що API-Conect - це не тільки про IT-шників в образі програмістів, чи служби підтримки. Це і про спеціалістів про розвитку цифрового бізнесу для управління продуктами та каталогом. Це і про контент менеджерів для управління порталом споживачів API. Ну і адміністратори безпеки які повинні розуміти, що і для чого вони адмініструють. Ну і хтось повинен статистику перетворити в рахунок для клієнта-споживача API.

3. Опис тестового стенду для вичення API-Connect

Архітектура тестового стенду показана на pic-09. Для тестування створено два Node.js Web Service:

pic-09

Вони задеплоєні на контейненій безсерверній платформі IBM Code Engine ну і на зовні виставлені публічні routs для доступу по http. Публічний роути зроблені тому, щоб порівнювати роботу через API-Connect та без нього. Ну і в навчальних цілях, щоб не мучитися з прокопуванням каналів. На роути WebServises виходить API-Connect. Ну, а споживачі API (API Consumers) вже виходять безпосередньо на API-Connect. Два WebServices зроблено для того, що спробувати більш складні варіанти роутінга, а не тільки простеньку proxy.

WebService1 являє собою прототип якогось банківського сервісу що робить пакетні зарахування, наприклад зарахування зарплати від різних компаній. Реалізовані такі api:

WebService2 являє собою модель сервісу перевірки ЕЦП да дешифрації. По факту він нічого не робить, але це допомже зробити складний роутінг через кілька сервісів

В загальному це повинно працювати так: Організація - клієнт банку є споживачем API. За допомогою API test-corporate-api.pdf Оорганізація себе реєструє в банку. Потім організація реєтрує підрозділи, що виплачують зарплату. Якщо організція не має філій то реєструється тільки один підрозділ. Ця оперція виконується за допомогою Branch API test-branch-api.pdf. За допомогою payment API test-payment-api.pdf організація передає в банк зарахування зарплати співробітникам. Кожний пакет зарахувань підписаний ЕЦП та зашифрований. Банк виконує опрацювання платежів, що передав клієнт за допомгою ProcessApi test-process-api.pdf

WebServic2 являє собою прототип якогось банківського сервісу що робить криптографічні перетворення. При отриманні пакетно зарахування зарплати співробітникам, цей сервіс виконує перевірку ЕЦП та дешифрацію плоатежу і уже на WebServic1 надходить “чистий” платіж. Це придумано для “усклаження” завдання роутинга.

Обидва сервіси написані на Node.js та імплементують Rest API. Параметри запитів типу branchid, corporateid , paymentid - передаються в path запиту.

4. Розробка бібліотеки API в API-COnnect

4.1. Загальний огляда

Найскладнішою для мене була частина розробки та тестування API. Тому з нього і почну Робота з продуктом починається з завантаження (чи підготовки) формалізованого опису API. Можна використовувати OpenApi3.0, OpenAPi2.0, SOAP WSDL.
Але я використовував тільки OpenApi3. Тому далі, мова буде тільки про OpenApi3.0. Формалізований опис повинен бути виконаний дуже акуратно з достатньою кількісю коментарів та деталізації, тому що ним, потім, будуть користуватися споживачі api. На pic-01 показано, як зайти в меню розробки API. Далі отримуємо екран з варіантами вибору методу створення API. Я пробував використовувати вбудований UI для підготовки опису API, але це виявилося витраченим часом. UI API-COnnect для підготовки OpenApi не доопрацьований. Тому рекомендую використовувати якиййсь тертій інструмент, на приклад Swagger Editor. Що треба вибрати, щоб імпортувати формалізований опис сервісу openapi3.0 показано на pic-10.

pic-10

Як виявилося UI API Connect не дозволяє описати єлементу масиву об’єктів. І, навіть, якщо у вас описані елементи масива, UI API-Connect іх не відобразить. Щоб побачити структуру масива треба переключитися в режим відображення файла, а не дивится через UI. Ну і валідація структури OpenAPI3.0 при імпорті теж не повноцінна. То й же приклад: масиви не описані, але файл втягується і валідація проходить успішно. Як прикад, на pic-11 показано, що відображається в UI на верхньому малюнку а що є на справді - на нижньому.

pic-11

Крім того в yaml файлі важливі відступи. Тому, на багатьох інструментах показані вертикальна решітка, що дозволяє легкто побачити кількість відступів. А тут, на нижньому малюгку, відступи відсутні - тобто набирати руками в такому редакторі дуже на зручно. Тому для підготовки формалізованих описів API та їх валідації потрібно використовувати сторонні програмні продукти.

4.2. Особливості підготовки формалізованного опису API в форматі openapi-3.0

В режимі редагування API видно ряд вкладок. На pic-12 показано призначення основних вкладок.

pic-12

У вкладці Design відображається опис методів, як в стандартному openapi. У вкладці Gateway відображаються додаткові реквізити, що додає в openapi файл API-Connect, що описують налаштування роутингу та трасфомації запитів. Все, що додав API-Connect знаходиться під специфічним заголовком: x-ibm-configuration

Далі показані відмінності слід знати в порівнянні з базовим openapi-3.0:

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        "200": # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: string

openapi: 3.0.0
info:
  version: 1.0.0
  title: Demo API Example
  x-ibm-name: demo-api-example
  description: Descriptino For Demo Api Example
# Особливість вказування url сервера. Потрібно вказувати не реальний URL а унікальний 
# аліас вашого сервера. Справа в тому, що є реальний EndPoint DataPower
# а цей аліас буде підставлятися EndPoint DataPower як Base URL
servers:
  - url: /demo-api-example
# -------------- Додатковий розділ, що описує рутинг APIGate, Що є в API-Connect  
x-ibm-configuration:
  properties:
    # Саме тут треба вказати реальний URL вашого сервіса
    target-url:
      value: http://example.com/operation-name
      description: The URL of the target service
      encoded: false
  # для того, щоб парцювали тестові запити cors: enabled: true  повинно бути
  cors:
    enabled: true
  gateway: datapower-api-gateway
  type: rest
  phase: realized
  enforced: true
  testable: true
  # Це розділ, де як раз і конфігурується роутинг в API GateWay
  assembly:
    execute:
      - invoke:
          title: invoke
          version: 2.0.0
          verb: keep
          target-url: $(target-url)
          follow-redirects: false
          timeout: 60
          parameter-control:
            type: allowlist
            values: []
          header-control:
            type: blocklist
            values: []
          inject-proxy-headers: true
          chunked-uploads: true
          persistent-connection: true
# ------------------------------------------------------          
paths:
  /:
    get:
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: string

Щоб розділ x-ibm-configuration: знаходився на початку yaml файлу, простіше зробити пустий файл за допомогою API-Connect, а потім збагатити його описом ваших методів.

Слід наголосити на особливостях задання параметрів запиту при підготовці формалізованого опису, а саме:

pic-14

На додаток, слід зауважити, що в специфікації openapi-3.0 ключ “operationid” є опціональний. Але на мій погляд, при конфігурації саме API-Connect, ця річ може допомогти при налаштуванні GateWay, тому бажано використовувати operationid “When to Use OperationId in OpenAPI?”.

4.3. Особливості налаштування GateWay

Лінки на документацію по конфігурації Gateway:

pic-13

Налаштування API GateWay теж має свої не очевидні особливості. Так, при створенні нового опису API, або заванатаженні існуючого, API-Connect додає найпростіший варіант роутингу, типу proxy pic-15. Як позначено на малюнку, роутинг відбувається на URL, що познчено контекстною змінною $(target-url). Але, з таким налаштуванням кубика “invoke”

pic-15

ваш сервіс не піде дальі root url, хоч як акуратно не прописуйте path’s в openapi. Для того, щоб компонент “invoke” розумів ваші path потрібно в полі URL прописати дві контекстні змінні ** $(target-url)$(api.operation.path) **, pic-16.

pic-16

При чому, роутинг працює навіть у випадку, коли в url (в path) у вас позначені параметри:

 /corporate-api/corporate/{corporateid}:
    get:
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    type: string
                  _rev:
                    type: string
                  type:
                    type: string
                  name:
                    type: string
                  contacts:
                    type: string
                  branches:
                    type: array
      operationId: get_corporate_by_id
      parameters:
        - name: corporateid
          in: path
          required: true
          schema:
            type: string

В попередніх розділах я згадував про необхідність заповнення operationid при опису методів openapi. А тепер хочу поазати як це можна використати. На приклад у вас для кожної operationid використовуються свої URL чи свої трансформації. Тому, вам потрібно побудувати розгалудження проксі по operationid. Реалізація цього способу показана на pic-17

pic-17

При підготовці опису API вам, раптом, API-Connect почне малювати помилку, що показана на pic-19.

pic-19

Не потрібно шукати помилок в вашому описі. Просто, воно вимагає включити захист API і помилка пропаде сама собою. Але, якщо у вас правильно сконфігуровано роутинг, то API буде працювати і з цією помилкою.

4.4. Тестування API

Після підготовки формалізованого опису API та налаштування роутингу потрібно все це протестувати. Щоб з’явилася можливість протестувати API, його потрібно перевести в режим on-line. Ознаки того, що API знаходиться в режимі off_line наведені на pic-20.

pic-20

Щоб перевести API в режим On-Line потрібно натиснути кнопку: Target Configuration та перевести в стан On слайдер Auto-Publish, pic-21. Переводити потрібно тоді, коли всі елементи модального віконця оновляться. Можливо API-Connect попросить вас погодитися на створення автопродукту (але це тільки перший раз).

pic-21

Зберігаємо, закриваємо вікно і повинні побачити, що API перейшло в режим On-Line та стала доступною вкладка EndPoint, pic-22.

pic-22

На вкладці EndPoint доступні реквізити: Client ID та Client secret, що будть використовуватися, якщо ви виберете варіант захисту вашого API як ApiKey.

tags: