Введение в 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 позволяет выполнять запросы и просматривать ответы.
- Чтобы перейти к веб-интерфейсу Swagger для API введите в адресной строке браузера
https://your-host/docs
, гдеyour-host
— доменное имя вашего сервера. - Отобразится страница 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"
).
Эта статья была полезна 2 чел.