Перейти к основному содержимому

Первый запрос

Редакция: OpenIDE Pro.

Файл сценария​

В окне Проект (Project) откройте контекстное меню папки и выберите Новый → Connekt Script (New → Connekt Script) — пункт стоит рядом с Kotlin Script. В диалоге «Create Connekt Script File» введите имя: файл получит расширение .connekt.kts, например orders.connekt.kts. В новом файле уже есть переменная val host и примеры GET- и POST-запросов.

DSL доступен на верхнем уровне файла: обёртки, main-функция и служебный код не нужны.

val host: String by env

GET("$host/api/orders") then {
assert(code == 200)
}

Запрос запускается из редактора — рядом с объявлением есть действие запуска. Результат открывается в панели запуска: код ответа, заголовки, тело и время выполнения. Оттуда же можно запустить все сценарии файла или выбранные, а тело ответа Connekt дополнительно сохраняет в файл и даёт на него ссылку.

Запросы разных типов в одном файле и результат запуска: заголовки, код ответа и тело в панели Run

Первый запрос не обязательно писать руками (Amplicode также создаёт целые сценарии для REST-контроллеров): для существующего в приложении эндпоинта запрос генерируется прямо из класса контроллера — URL, метод и заголовки подставляются сами.

Генерация запроса от эндпоинта: действие Generate HTTP Request в контроллере и выбор из списка эндпоинтов приложения

Как читается скрипт​

Скрипт регистрирует запросы, а не выполняется сверху вниз. Отсюда несколько правил, которые важно знать сразу:

  • на верхнем уровне между запросами не должно быть императивного кода: присваиваний, if, вывода в консоль;
  • проверки живут только внутри блоков then { } и useCase { };
  • результат одного запроса не подставляется в строку URL другого — для этого есть pathParam.

На верхнем уровне допустимы: чтение переменных окружения (val x by env), data class, configureClient, объявление OAuth (val x by oauth(...)), функции-расширения и объявления самих запросов.

Конфигурация запроса​

val host: String by env
val apiKey: String by env

GET("$host/api/orders", name = "Список заказов") {
header("X-Api-Key", apiKey)
accept("application/json")
queryParam("status", "created")
queryParam("limit", 20)
}

Доступны header, headers, contentType, accept, queryParam, queryParams, pathParam, а также опции запроса: noRedirect(), noCookies(), http2().

Cookies по умолчанию хранятся в сессии автоматически. Редиректы 3xx по умолчанию отслеживаются.

Тело запроса​

POST("$host/api/orders") {
contentType("application/json")
body("""{"productId": 42, "quantity": 1}""")
}

Форма:

POST("$host/api/login") {
formData {
field("username", "alice")
field("password", "secret")
}
}

Общие заголовки для нескольких запросов​

Повторяющуюся конфигурацию удобно вынести в функцию-расширение на RequestBuilder:

fun RequestBuilder.withApiKey() {
header("X-Api-Key", apiKey)
}

GET("$host/api/orders") {
withApiKey()
}

Разбор ответа​

Внутри блока then доступен объект ответа: code, body, header("Name").

val orders by GET("$host/api/orders") then {
decode<List<Order>>("$.content")
}

decode<T>() десериализует JSON. Без аргумента разбирается корневой объект, с аргументом — значение по JSONPath. Тело ответа читается один раз: сохраните результат в переменную и работайте с ней.

Обратите внимание на by в примере выше: именно делегат связывает переменную со значением из ответа. Знак = даст другой результат — подробнее в разделе Переменные и кеширование.

Подключение других скриптов и зависимостей​

@file:Import("shared_auth.connekt.kts")
@file:DependsOn("com.example:my-lib:1.0.0")

Объявления верхнего уровня из импортированного скрипта становятся доступны, транзитивные импорты работают.