Введение в API — Версия 4 — База знаний Comindware

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

Comindware Business Application Platform обладает встроенной библиотекой API. Чтобы туда попасть, введите /docs в поисковой строке браузера после вашего доменного имени. Вы попадете на страницу Comindware Business Application Platform API, где вы увидите доступные для использования API:

RESTful Web Api (см. статью Методы RESTful Web Api):
System Core Api (см. статью Методы System Core API);
Solution Api (см. статью Методы Solution API).

Наиболее часто используются методы REST API. В целом, REST API работает посредством отправки простых web-запросов (в формате URL ссылки) от одной системы к другой для выполнения определенных действий (например, запросить информацию, передать данные, инициировать какое-либо действие в другой системе и т.д.). Эти методы широко распространены в современных системах и зачастую вы можете найти всю необходимую документацию по его использованию для конкретной системы, просто погуглив «<название системы> REST API».

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

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

Конечно, второй тип запросов наиболее гибок и позволяет сформировать более сложный и структурированный запрос, но существенным минусом этого метода является то, что данный запрос нельзя протестировать с помощью браузера. Данный тип запросов вы можете протестировать только с помощью, например, Postman.

Comindware Business Application Platform обладает REST API, что позволяет как инициировать API запросы, так и принимать их.

Инициировать запрос к другой системе можно следующими способами:

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

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

Инициировать запрос из другой системы можно следующими способами:

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

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