Введение в API

---

Введение

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

• Solution API
• System Core API
• Web API

Доступ к API

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

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

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

Методы API

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

• GET — получить список всех записей.
• GET {id} — получить данные о записи с идентификатором {id}.
• DELETE {id} — удалить запись с идентификатором {id}.
• POST — создать новую запись.
• PUT {id} — изменить данные о записи с идентификатором {id}.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Чтобы перейти к странице Swagger, введите в адресной строке браузера строку 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).
3. Перейдите на страницу требуемого API.
4. Раскройте требуемый метод API в списке.
5. Выберите формат запроса и ответа в поле Response Content Type.
6. Запустите любой из доступных методов, нажав кнопку Try it out.
7. Отобразится заготовка запроса: 
   • Request URL — скопируйте эту строку во внешнюю систему в качестве URI запроса, для запросов GET и DELETE она содержит весь запрос;
   • Example Value — скопируйте эту строку во внешнюю систему в качестве тела запроса.

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

Для создания шаблона записи с помощью System Core API отправьте следующий POST-запрос на адрес Request URL, указанный в 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").

Связанные статьи

Методы Solution API 

Методы System Core API 

Методы Web API 

‌ К началу

---

Номер Статьи: 2080
Размещено: Wed, Apr 20, 2022
Последнее обновление: Mon, Nov 18, 2024

Online URL: https://kb.comindware.ru/article/vvedenie-v-api-2080.html