1. Назначение API
Прикладной программный интерфейс (ApplicationProgrammingInterface, далее API или интерфейс) системы А предназначен для интеграции её веб-сервиса в стороннюю информационную систему В, установленную на интранет-сервере для его использования в автоматизированном режиме для решения прикладных задач.
2. Подключение к интерфейсу API
Для работы с системой А через интерфейс API необходимо подключение услуги доступа к API и наличие среды разработки или языка программирования, в которых реализована поддержка работы с веб-сервисами или протоколом SOAP (наличие WSDL-спецификации позволяет разработчику автоматически сгенерировать описание класса SOAP-клиента для упрощения доступа к серверу с API.
Процедура авторизации может быть основана на механизме HTTP-авторизации, при этом параметры авторизации (логин и пароль к личному кабинету) передаются при вызове каждого метода интерфейса.
3. Типовой (тестовый) сценарий использования
1. Создание нового сеанса: Метод createTestingSession().
2. Получение ссылки для сеанса: Метод getTestingSessionUrl().
3. Загрузка полученной ссылки во фрейм на странице системы В.
4. Периодическая проверка статуса сеанса: Метод isTestingSessionComplete().
5. По окончании – получение ссылки на результат: Метод getResultsReportUrl().
6. Загрузка полученной ссылки во фрейм на странице системы В.
7. Получение результатов в другом формате: Методы: getResultsReportHtml().
8. Сохранение полученных результатов в других форматах в системе.
Типовой алгоритм взаимодействия портала В с системой А будет выглядеть следующим образом:
4. Методы интерфейса
В состав интерфейса входят методы, которые можно разделить на следующие группы:
- Методы для работы с каталогом сервисов;
- Методы для управления сервисами;
- Методы доступа к результатам;
- Методы для работы с настройками сервиса;
- Дополнительные методы.
4.1 Методы для работы с каталогом сервисов
Получение списка/атрибутов сервисов getTestScalesList()/getTestAttribs().
4.2 Методы для управления сервисами
Запуск/завершение сервиса с заданным идентификатором сеанса createTestingSession().
4.3 Метод доступа к результатам
Получение адреса страницы отчета по результатам выполнения сервиса getResultsReportUrl()
4.4 Метод для работы с настройками сервиса
Получение настроек прерывания сервиса getTestSettingsInterrupts()
4.5 Дополнительные методы
Получение номера текущей версии интерфейса getApiVersionNumber().
Входные параметры: отсутствуют
5. Сложные типы данных
В методах интерфейса используются как простые, так и сложные (комплексные) типы данных. Как правило, в качестве аргументов методов используются простые типы данных (строки и целые числа), а в качестве возвращаемых результатов – сложные (структуры и массивы).
Результат выполнения любого метода интерфейса содержит структуру данных OperationStatus сложного типа TypeOperationStatus, которая содержит такие поля, как числовой код результата выполнения метода (номер ошибки), мнемонический код результата (мнемокод ошибки) и текстовое описание результата (текст сообщения об ошибке). Значение полей этой структуры можно использовать для протоколирования номера ошибки и для вывода пользователю системы текста сообщения о возникшей ошибке.
Описание типа:
<xsd:complexType name="TypeOperationStatus">
<xsd:sequence>
<xsd:elementminOccurs="1" maxOccurs="1" name="ErrorNumber" type="xsd:int"/>
<xsd:elementminOccurs="1" maxOccurs="1" name="ErrorCode" type="xsd:string"/>
<xsd:elementminOccurs="1" maxOccurs="1" name="ErrorMessage" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
Назначение полей:
- ErrorNumber - числовой код выполнения операции (номер ошибки);
- ErrorCode - мнемонический код выполнения операции (мнемокод ошибки);
- ErrorMessage - текстовое описание ошибки.
В случае отсутствия ошибок при выполнении метода номер ошибки равен нулю (ErrorNumber=0), а мнемокод ошибки содержит строку "OK" (ErrorCode="OK").