Использование 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 он еще и идемпотентен (зарезервировано)