Введение в API

Введение

Comindware Platform может обращаться к API внешних систем через подключения и пути передачи данных, а также может обрабатывать запросы из внешних систем через интерфейсы REST API трёх типов:

Solution API — обеспечивает доступ к актуальной модели и бизнес-логике конкретного приложения.
System Core API — предоставляет доступ к системным функциям (управление аккаунтами, системными службами и т.д.).
Web API — универсальные методы прикладного уровня для работы с данными (излечение записей, базовые CRUD-операции).

Стратегия выбора API

Перед выбором API ознакомьтесь с параграфом «Обратная совместимость API».

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

Чтобы выбрать оптимальные API в соответствии с целями и потребностям вашего предприятия, обязательно привлеките системных аналитиков, бизнес-аналитиков и представителей коммерческих отделов вашей организации.

В общем случае можно рекомендовать следующий подход к выбору API:

Для интеграций с бизнес-логикой приложений используйте Solution API. При этом предусмотрите механизм обработки изменений логики работы приложений.
Для системных задач (аутентификация, настройки) используйте System Core API. Учитывайте, что при обновлении мажорной версии ПО (например, с 4.2 на 5.0) может потребоваться обновить код интеграций.
Для стабильных и долгосрочных интеграций отдавайте предпочтение Web API. Эти интерфейсы обладают наибольшей обратной совместимостью.

Обратная совместимость API

Для API Comindware Platform различных типов применяются разные политики обратной совместимости.

Solution API

Обратная совместимость: не гарантируется и может меняться в при внесении изменений в приложения, за исключением метаданных (например, базовой структуры сущностей Comindware Platform).
Рекомендации: используйте для интеграций, где требуется доступ к текущей модели приложения. Учитывайте, что модель данных и логика работы приложения методы могут меняться по мере его развития.

System Core API

Обратная совместимость: поддерживается в рамках мажорной версии (например, 5.x.x). Методы сохраняют стабильность, но в новых минорных версиях могут быть реализованы новые параметры или возможности с сохранением совместимости.
Рекомендации: при обновлении мажорной версии (например, с 4.x.x на 5.0.0) проверяйте документацию на наличие изменений. Для минорных версий (например, 5.1 и 5.2) совместимость сохраняется.

Web API

Обратная совместимость: полностью гарантирована. Методы остаются стабильными между всеми версиями Comindware Platform (например, 4.x.x и 5.x.x).
Рекомендации: оптимально подходит для долгосрочных интеграций. Изменения вносятся только в исключительных случаях, с сохранением обратной совместимости.

Определения

API (Application Programming Interface) — это интерфейс прикладного программирования — набор методов, классов, библиотек и функций, обеспечивающих возможность взаимодействия между системами.
REST API — это API, соответствующий архитектуре Representational State Transfer (передача репрезентативного состояния). Преимуществами REST API являются возможность оптимального использования протокола HTTP, масштабирования сервисов и разработки приложений с использованием практически любых языков программирования с соблюдением принципов проектирования REST:
- отсутствие сохранения состояния на сервере — каждый поступающий запрос содержит все необходимые для обработки данные и обрабатывается независимо от других запросов;
- единообразный интерфейс — сервер передаёт информацию в стандартном формате;
- независимость клиента и сервера — клиент может взаимодействовать с сервером только посредством URI ресурса, а сервер может лишь передавать на клиент запрошенные данные посредством HTTP;
- возможность кэширования ресурсов — ответы содержат данные о кэшируемости, запрашиваемые многократно ресурсы могут кэшироваться на стороне сервера или клиента;
- многоуровневая архитектура системы — клиент может подключаться к авторизованным посредникам между клиентом и сервером, чтобы получать ответы от сервера, а сервер может передавать запросы другим серверам;
- код по запросу — сервер может расширить возможности клиента, передав исполняемый код, например, для проверки введённых пользователем данных.
RESTful — это веб-служба, реализующая архитектуру REST.
Ресурс — это объект или информация в приложении, например шаблон, аккаунт или документ, доступ к которым предоставляет API.
URI ресурса — это универсальный идентификатор ресурса в API.
Клиент — это человек или система, которые осуществляют доступ к ресурсам посредством API.

Доступ к API

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

Все интеграции с помощью REST API настраиваются по одному принципу:

составьте сценарий интеграции — какая система инициирует вызов API, как часто, какие методы она использует для передачи каких данных, что потом происходит и т. д.;
используйте документацию по API для тестирования запросов, настройки подключения и формирования финальных «рабочих» запросов.

Методы API

Comindware Platform поддерживает следующие методы API.

GET — получить данные об объекте.
DELETE — удалить объект.
POST — создать новый объект.
PUT — изменить данные объекта.

Инициация запроса из внешней системы

Comindware Platform может принимать HTTP-запросы к API двумя способами:

Запрос GET или DELETE в виде URL-строки, содержащей все параметры запроса.
- Внешняя система отправляет запрос в строке URL. Заготовку запроса для внешней системы можно сформировать в интерфейсе Swagger.
- Такой запрос можно проверить с помощью браузера: скопируйте полученный Request URL в адресную строку и нажмите клавишу Enter. Если вы уже вошли в систему в этом браузере, аутентификация не потребуется.
Запрос POST или PUT с телом, содержащим все параметры (например, имя пользователя и пароль, данные, которые необходимо отправить или получить и т. д.).
- Внешняя система отправляет запрос в формате JSON или XML. Заготовку запроса для внешней системы можно сформировать в интерфейсе Swagger.
- Этот вариант является более гибким, позволяя передать гораздо больше данных в структурированном виде. Но такой запрос нельзя протестировать с помощью браузера. Для тестирования можно использовать встроенный веб-интерфейс Swagger или такие службы, как Postman, SoapUI, Insomnia и т. п.
Comindware Platform возвращает ответ формате JSON или XML.

Аутентификация внешних систем при доступе к API

API Comindware Platform поддерживает два способа аутентификации внешних систем:

Basic-аутентификация — требуется передать имя пользователя и пароль аккаунта, от имени которого будет выполняться запрос;
HMAC — требуется передать токен и секретный ключ, сформированные для аккаунта на странице «Администрирование» – «Ключи аутентификации».

Примечание

Для использования методов API и интерфейса Swagger следует создать специальный аккаунт и предоставить предоставить ему разрешение «Вызов API» в системной роли. См. «Системные роли. Определения, настройка, объединение, удаление». Кроме того, API и Swagger могут использовать пользователи, входящие в системную роль «Системные администраторы».
При вызове методов API в интерфейсе Swagger на странице https://your-host/docs уже выполнен вход в Comindware Platform, и дополнительная аутентификация не требуется.
При вызове методов API из внешней системы в запросы необходимо добавлять заголовки для аутентификации с использованием аккаунта, которому предоставлен доступ к API.
Большинство внешних систем обладают интерфейсом настройки метода аутентификации, при отсутствии такового добавьте в Header запроса параметр Authorization, содержащий зашифрованные в формате Base64 имя пользователь и пароль.

Инициация запроса к внешней системе

REST API широко применяется в современных системах, и зачастую найти документацию по использованию API конкретной системы можно, введя в поисковой системе запрос вида «<название системы> REST API».

Comindware Platform поддерживает перечисленные ниже способы обращения к API внешних систем:

Запрос отправляет скрипт на C# (вызываемый кнопкой или задачей выполнения сценария в процессе). Скрипт устанавливает подключение к внешней системе, формирует запрос, отправляет его и получает ответ.
Запрос формирует и отправляет сценарий посредством настроенного подключения к внешней системе. Сценарий позволяет сформировать тело запроса, проанализировать полученный ответ и поместить из него данные в атрибуты записей.
Запрос формирует и отправляет промежуточное или конечное событие отправки сообщения в процессе.

Примечание

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

Аутентификация при доступе к API внешних систем

При доступе из к внешним API используйте метод аутентификации, который поддерживает внешняя система. Обратитесь документации API этой системы, чтобы узнать, следует ли указывать имя пользователя b пароль в URL-адресе или теле запроса, или необходимо сгенерировать и использовать токен безопасности вместо передачи пароля в виде обычного текста.

Использование Swagger

Comindware Platform предоставляет встроенный веб-интерфейс API на основе Swagger.

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

Чтобы перейти к странице Swagger, введите в адресной строке браузера строку https://your-host/docs, где your-host — доменное имя вашего сервера.
Отобразится страница Comindware Platform API со следующими разделами:
- RESTful Web API — общие методы для всех версий ПО (см. Методы Web API);
- System Core API — системные методы, которые могут отличаться для разных версий ПО (см. Методы System Core API);
- Solution API — методы для шаблонов бизнес-приложений (см. Методы Solution API).
Перейдите на страницу требуемого API.
Раскройте требуемый метод API в списке.
Выберите формат запроса и ответа в поле Response Content Type.
Запустите любой из доступных методов, нажав кнопку Try it out.
Отобразится заготовка запроса:
- Request URL — скопируйте эту строку во внешнюю систему в качестве URI запроса, для запросов GET и DELETE она содержит весь запрос;
- Example Value — скопируйте эту строку во внешнюю систему в качестве тела запроса.

Страница Swagger UI с разделами API Comindware Platform

Пример вызова метода System Core API

Для создания шаблона записи с помощью System Core API отправьте следующий POST-запрос на адрес Request URL, указанный в Swagger:

http://your-host/api/public/system/TeamNetwork/ObjectAppService/Create

Вместо your-host укажите адрес экземпляра Comindware Platform.
В теле запроса (body) укажите системное имя шаблона записи (например, "Car").
В ответ на запрос Comindware Platform вернёт ID созданного шаблона записи (например, "oa.1").

Введение в API