Використання REST API

Загальний підхід

Для зовнішнього взаємодії з платформою використовується RESTful API, однак з огляду на підтримку Legacy-систем (неможливість редагування записів через метод PUT), запропонований API є ідемпотентним щодо всіх методів включаючи POST:

Загальний перелік REST-сутностей і відношень між ними визначається розробниками плагінів і об'єднуються в домени (наприклад, для поділу Customers телеком оператора і Customers Фінтех сектора) - прикладом назви домену є bss в наступному url:
http://servername:port/api/v1/Bss/addresses/actions/sync.json?lang=uk

слід звернути увагу на формування url для вказівки відносин сутностей - що фактично реалізує принцип передачі параметра ParentID при створенні конкретної REST суті - за прикладом нижче ми бачимо створення суті Subscribers в раніше створеної суті Customers з ідентифікатором 10000001:
POST http://servername:port/api/v1/Bss/customers/1000001/subscribers.json?lang=uk

Важливо розуміти, що прозорість архітектури для всіх розробників платформи досягається стандартизацією іменування сутностей - тому обов'язковою рекомендацією є іменування сутностей іменниками множини, а виконання операцій для них - дієсловами. На прикладі нижче виконається операція активації раніше створеного абонента з ідентифікатором 2000101:
POST http://servername:port/api/v1/Bss/subscribers/2000101/activate.json?lang=uk

Операції можуть бути застосовані для різних сутностей - це також визначається розробникам конкретного плагіна, що реалізує конкретні сутності. На прикладі нижче представлений метод зміни статусу для різних сутностей:
POST http://servername:port/api/v1/Bss/subscribers/2000101/changeStatus.json?lang=uk
POST http://servername:port/api/v1/Bss/customers/1000001/changeStatus.json?lang=uk

У разі необхідності зміни раніше створеної REST суті слід використовувати метод PUT і унікальний ідентифікатор REST суті -нижче наведено приклад редагування даних Customers:
PUT http://servername:port/api/v1/Bss/customers/1000001.json?lang=uk

Фактично для індикації відносини сутностей між собою використовується концепція явної вказівки на вищу сутність (Entity) через параметр ParentID в значенні Path формату Entity / {ParentID} / SubEntity, нижче наведений приклад взаємозв'язків сутностей Associations, Customers і Subscribers, включаючи підпорядковані їм сутності (Sub- Entity) Contracts, Profiles, Addresses і Properties:

Background API взаимодействия

Service Flow

API Layer:реалізує REST http-інтерфейс, авторизацію, кешування і ідемпотентність викликів.
Backend Plugin: реалізує бізнес-логіку, наприклад CRUD-операції для сутності (наприклад Customers).

Ідемпотентність: логіка обробки параметра global_unique_id

Параметр global_unique_id використовується для виключення дублювання вставки даних в БД - кожна успішна CRUD операція, в тому числі і для методу POST, зберігається в розподілений кеш сервера Веб-публікацій (реалізований на рівні окремої БД MS SQL Server - SQL Server distributed cache Microsoft.Extensions.Caching. SqlServer package) і в разі отримання повторного запиту, API повертає раніше збережений відповідь з кешу. Запит ідентифікується як повторний за значенням global_unique_id.

Тіло відповіді завжди містить вказівку статусу перевірки (" IsCompleted " інформує про те, що спрацювала перевірка на ідемпотентність і тіло відповіді використано з кешу Веб-сервера, в значення « Added » говорить про те, що перевірка негативна і результат виконання доданий в кеш, приклади нижче - важливо розуміти при цьому, що тег data буде містити Response-модель даних конкретної сутності Entity:

{
"headerId": "1892ae73-f1db-47e0-9084-35e8aef993f3",
"idempotent": {
"status": "IsCompleted",
"dateModify": "2019-06-09T15:53:18.5599139Z",
"data": {
"id": 100000257,
"lang": "uk ",
"idType": 1

} } }

{
"headerId": "1892ae73-f1db-47e0-9084-35e8aef993f3",
"idempotent": {
"status": "Added",
"dateModify": "2019-06-09T15:53:18.5580444Z",
"data": {
"id": 100000257,
"lang": "uk ",
"idType": 1

} } }

Авторизація API

Для авторизації на методах API реалізована підтримка різних типів авторизації на рівні кожного контролера в 2-х режимах розгортання платформи - Internet і Intranet, підтримувані типи авторизації для кожного типу розгортання перераховані нижче:

Internet:

  • Basic Authorization
  • oAuth 2.0

Intranet:

  • URL (токен)
  • Basic Authorization
  • Kerberos
  • NTLM

Таким чином, для авторизації на методах API досить використовувати Basic Authorization на рівні передачі заголовків http запиту. Актуальні значення пари логін-пароль слід запитати у адміністратора вашої організації.

Для використання авторизації через токен в URL слід передавати значення Authorization = , де - стандартна форма для схеми авторизації - Basic Authorization. Важливо розуміти, що так як передача йде через урл, то у вигляді Url Encoded, наприклад:

http://servername:port/api/v1/Bss/versioninfo.json?Authorization=eWl6aGFja0BnbWFpb1234206VGVzdDEyMzQ1Ng%3D%3D

Формат дати та часу для параметрів API

Для передачі параметрів в форматі дати і часу використовується формат ISO 8601 , приклад дати і часу в цьому форматі для Києва (Європа): 18.06.2019 0:00:00 буде 2019-06-18T00:00:00+03:00

Методи API

Призначення HTTP методів

Маппінг необхідних Вам операцій на HTTP методи легшає, коли ви знаєте характеристики всіх методів HTTP - оскільки в реалізації REST API використовуються HTTP методи для операцій замість написання різних найменувань сервісів для кожної операції, в цьому розділі розглядається поведінка кожного HTTP методу. Нижче представлений список методів, які використовуються в REST додатках і показані їх властивості по відношенню до кожної сутності Entities:

  • GET: цей метод є безпечним і ідемпотентним. Зазвичай використовується для отримання інформації і не має побічних ефектів
  • POST: цей метод не є безпечним, проте в реалізації REST API він ще є ідемпотентним - це зроблено для підтримки можливості зміни в Legacy-системах, що не підтримує метод PUT. Цей метод найбільш завжди використовується для створення сутностей Entities
  • PUT: цей метод є ідемпотентним спочатку - тому краще використовувати цей метод замість POST для відновлення ресурсів. Уникайте використання POST для відновлення ресурсів, крім тих сутностей Entities де зміни вимагають історичності змін, наприклад Addresses або Profiles
  • DELETE: як випливає з назви, цей метод використовується для видалення сутностей Entities, проте в реалізації REST API він ще є ідемпотентним (зарезервовано)