Перейти к основному содержимому
Версия: 1.20.1

Настройки REST API

Модуль Настройки REST API предоставляет возможность создания пользовательских веб-API для интеграций экземпляра с внешними приложениями. Вы можете определить серверный скрипт, вызываемый REST запросом из внешней системы. Скрипт может обрабатывать параметры запроса, выполнять действия на экземпляре и формировать ответ. В результате настройки REST API создается конечная точка для обращений из внешних систем, в том числе с других экземпляров SimpleOne.

подсказка

Необходимая роль: admin.

Настройка конечной точки​

Чтобы настроить конечную точку, выполните следующие шаги:

  1. Создайте модуль API. Для этого перейдите в Настройки REST API→ Модули API.

  2. Заполните поля:

    • Наименование – укажите название модуля API.
    • Путь – укажите относительный путь к модулю API, например, support.
    • Активен – установите флажок, чтобы активировать модуль. Это позволит выбирать его в таблицах Версия API, Действия API и Параметры модуля запроса API.

  3. Нажмите Сохранить или Сохранить и выйти. После этого в связанном списке Версия API будет создана запись версии API.

  4. Нажмите на созданную запись версии API, чтобы открыть ее. При необходимости в связанном списке можно создать дополнительные записи версии модуля API, например, v2.

    • Модуль – укажите модуль API, который был создан ранее для этой версии.
    • Активный – установите флажок, чтобы активировать данную версию. При отсутствии отметки эту версию будет невозможно выбрать в связанных таблицах (Действия API).
    • Путь – укажите путь к версии API, например, v1.

    Первая версия v1 создается автоматически при создании модуля API. Запросы API без конкретной версии используют последнюю активную версию модуля.

  5. В связанном списке перейдите Действия API → Создать.

    ПолеОписание
    НаименованиеНазвание действия.
    ПутьУкажите путь к действию API.
    АктивныйУстановите флажок, чтобы сделать действие активным. Если действие не отмечено как активное, его будет нельзя выбрать в связанном списке API Action Request Parameter.
    Требуется аутентификацияУстановите флажок, если запросу необходима аутентификация перед выполнением. По умолчанию выбрано.
    МодульВыберите модуль API, созданный ранее (модуль должен быть активным). Это поле ссылается на таблицу Модули API (sys_api_module).
    ВерсияВыберите версию API, созданную ранее (версия должна быть активной). Это поле ссылается на таблицу Версии API (sys_api_version).
    HTTP-методВыберите метод, который включает в себя это действие. Например, GET или POST.
    СкриптУкажите скрипт, реализующий указанное действие. Используйте серверные классы SimpleApiRequest и SimpleApiResponse side API.
примечание

Вы также можете настроить действие API, скрипт которого будет запускаться при запросе к действию.

Запрос к действию может выполняться с указанием версии:

{your_instance_url}/v1/api/{application}/{module_path}/{version}/{action_path}

и без указания версии:

{your_instance_url}/v1/api/{application}/{module_path}/{action_path}

Запросы API без указания версии используют последнюю активную версию модуля.

  1. Заполните поля Наименование и Путь. Пример значения в поле Путь: tickets-count.
  2. В поле HTTP-метод, укажите метод для вызова действия.
  3. В поле Скрипт, укажите, какой скрипт необходимо вызвать при REST запросе на действие. Для работы с запросами REST API на платформе SimpleOne созданы классы SimpleRestRequest и SimpleRestResponse. Объекты данных этих классов доступны в скрипте Действие API. Пример:
Действие API
(function (request, response) {
    const reqBody = request.getBody();
    response.setBody({
        "body": JSON.stringify(reqBody),
        "count": 1
    })
})(SimpleApiRequest, SimpleApiResponse)
  1. Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
  2. Вы можете настроить Параметры действия запроса API, связанные с действием. Для каждого параметра можно указать обязательность:

При попытке отправить запрос без обязательного параметра в ответе будет содержаться сообщение вида:

{"error":"Required parameter param_1 not sent.","timing":{"before_echo": ...}}

Вызов конечной точки​

Для вызова конечной точки используйте следующий формат URL:

https://your_instance_url/v1/api/applicationSlug/module_path/version/action_path?params

где:

  • your_instance_url – URL вашего экземпляра.
  • applicationSlug – значение поля Слаг того приложения, для которого создается эта конечная точка.
  • module_path – значение поля Путь, указанное в модуле API.
  • version – значение поля Путь, указанное в версии API.
  • action_path – значение поля Путь, указанное в действии API.
  • params – параметры GET.

Пример URL для вызова конечной точки:

https://sandbox-01.dev.simpleone.ru/v1/api/c_simple/api_module_path/api_action_path?param_1=value_1

Авторизация​

Вы можете отправлять запросы в Scripted REST API при помощи Bearer токена или без авторизации. Тип авторизации запросов зависит от значения флажка Требуется аутентификация на форме Действие API.

Запрос на действие API, не требующий авторизации (Требуется аутентификация = Нет), выполняется под пользователем Guest User:

Запросы с недействительными Bearer токенами также выполняются под пользователем Guest User.

Для Basic Auth авторизации запросов к Scripted REST API выполните следующие шаги:

  1. Настройте отправку POST запроса /v1/auth/login с Basic Auth из внешней системы на экземпляр для получения токена.
  2. Настройте отправку запроса к Scripted REST API с полученным токеном.

Схема авторизации:

Пример серверного скрипта с использованием Simple API для получения токена через POST запрос с авторизацией Basic Auth:

Пример

const simpleInstanceUri = ss.getProperty('simple.instance.uri');
const URL_BASE = (simpleInstanceUri.startsWith('https://')) ? simpleInstanceUri : `https://${simpleInstanceUri}`;
const authRequest = sws.restRequestV1();
authRequest.setRequestUrl(`${URL_BASE}/v1/auth/login`);
authRequest.setRequestMethod('POST');
authRequest.setRequestHeader('Content-type', 'application/json');
const payload = {
    "username": "admin",
    "password": "qwerty123456"
}
authRequest.setRequestBody(JSON.stringify(payload));
const authResponse = authRequest.execute();
if (JSON.parse(authResponse.getBody()).status === 'ERROR') {
  ss.error(JSON.parse(authResponse.getBody()).errors[0].message);
  ss.info('Check credentials at 10..11 lines of current script');
  return;
}
ss.info(JSON.parse(authResponse.getBody()).data.auth_key);
// Информация: 5WvOT9Ejlxd6Gb8bkCWMtG3XXMYcoDDJ

Поддерживаемые типы Content-Type​

Для получения тела запроса в скрипте API действия вызывайте метод getBody() для объекта request.

Ниже представлен пример тестового скрипта для API действия:

Действие API
(function (request, response) {
    
    const reqBody = request.getBody();
    const bodyForResponse = typeof reqBody === 'string' ? reqBody : JSON.stringify(reqBody);
    response.setBody({
      "request_body_type": typeof reqBody,
      "request_body": bodyForResponse
    })
    
})(SimpleApiRequest, SimpleApiResponse)

Используйте следующие типы Content-Type types для запросов, отправляемых на API действие:

  • application/json
  • application/jsonp
  • application/xml
  • text/xml
  • text/html
  • text/plain

Отправка POST запроса с телом в виде JSON​

Отправка POST запроса с телом в виде XML​

Отправка POST запроса с телом в виде HTML​

Отправка POST запроса с телом в виде текста​

Ответ API действия​

Чтобы сформировать ответ действия API, используйте объект response:

response.setBody({
      "count": 100,
      "status": "OK",
      "error_message": ""
    })

В ответ действия API включен ключ timing со значением времени выполнения скрипта API действия:

"timing": {
      "before_echo": 0.0884089469909668
  }