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

Введение в API

Общие сведения

Помимо встроенных инструментов, обеспечивающих взаимодействие с внешними службами через подключения и пути передачи данных, Comindware Business Application Platform может взаимодействовать с внешними системами через API трех типов: Web API, System Core API и Solution API.

API (Application Programming Interface) — это интерфейс прикладного программирования, набор методов, классов, библиотек и функций, обеспечивающих возможность взаимодействия между системами.

Comindware Business Application Platform предоставляет REST API, обеспечивающий как отправку, так и приём HTTP-запросов для выполнения таких действий, как обмен данными, выполнение операций т. п.

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

Как правило, запросы REST API бывают двух типов:

  • URL-строка, содержащая все параметры, необходимые для формирования запроса к системе. Данный тип запроса можно протестировать в браузере;
  • тело запроса, в котором перечислены все необходимые параметры (например, имя пользователя и пароль, данные, которые необходимо отправить или получить и т. д.). Этот тип наиболее гибок и позволяет формировать сложные структурированные запросы. Но такой запрос не удастся протестировать с помощью браузера. Для тестирования таких запросов можно использовать встроенный в Comindware Business Application Platform веб-интерфейс Swagger или такие службы, как Postman, SoapUI, Insomnia и т. п.

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

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

  • Swagger предоставляет подробную справку по методам API, включая описания запросов и ответов, а также модели данных с примерами значений.
  • Swagger позволяет выполнять запросы и просматривать ответы.
  1. Чтобы перейти к веб-интерфейсу Swagger для API введите в адресной строке браузера https://your-host/docs, где your-host — доменное имя вашего сервера.
  2. Отобразится страница Comindware Business Application Platform API со следующими разделами:
    • RESTful Web API — общие методы для всех версий ПО (см. Методы Web API);
    • System Core API — системные методы, которые могут отличаться для разных версий ПО (см. Методы System Core API);
    • Solution API — методы для шаблонов бизнес-приложений (см. Методы Solution API).

Способы вызова методов API

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

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

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

Примечание

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

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

  • Внешняя система отправляет запрос в строке URL в Comindware Business Application Platform. На странице /docs/WebApi/ вы можете запустить любой из доступных методов, нажав кнопку «Try it out!», и получить заготовку Request URL, по которой следует формировать запрос из внешней системы. 
  • Внешняя система отправляет запрос в формате JSON или XML в Comindware Business Application Platform. Заготовку тела запроса для требуемого метода вы можете получить на странице /docs/WebApi/, скопировав её из поля «Example Value» с выбранным форматом (Response Content Type).

Примечание

Перед доступом к странице /docs и использовании Swagger вы выполняете вход как пользователь Comindware Business Application Platform.

При вызове методов API из внешней системы в запросы необходимо добавить заголовки для аутентификации с использованием аккаунта, которому разрешено выполнять действия вызываемых методов. См. «Роли в приложении. Определения, настройка, объединение, удаление» и «Стандартные системные роли».

API Comindware Business Application поддерживает Basic-аутентификацию и HMAC-аутентификацию.

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

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

http://your-host/api/public/system/TeamNetwork/ObjectAppService/Create
  • Вместо your-host укажите адрес экземпляра Comindware Business Application Platform.
  • В теле запроса (body) укажите системное имя шаблона записи (например, "Car").
  • В ответ на запрос Comindware Business Application Platform отправит ID созданного шаблона записи (например, "oa.1").