Первый запрос
Редакция: 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 дополнительно сохраняет в файл и даёт на него ссылку.
Первый запрос не обязательно писать руками (Amplicode также создаёт целые сценарии для REST-контроллеров): для существующего в приложении эндпоинта запрос генерируется прямо из класса контроллера — URL, метод и заголовки подставляются сами.
Как читается скрипт
Скрипт регистрирует запросы, а не выполняется сверху вниз. Отсюда несколько правил, которые важно знать сразу:
- на верхнем уровне между запросами не должно быть императивного кода: присваиваний,
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")
Объявления верхнего уровня из импортированного скрипта становятся доступны, транзитивные импорты работают.