GraphQL-запрос в Tetiva строится вокруг схемы: приложение делает интроспекцию эндпоинта или читает схему из файла, а дальше подсказывает поля, генерирует пример операции и подсвечивает ошибки прямо в редакторе. Отправляется обычный POST с JSON-телом query / variables / operationName, поэтому всё, что вы знаете про заголовки и авторизацию в HTTP, работает и здесь.
Загрузка схемы#
Введите адрес эндпоинта (https://api.example.com/graphql) и нажмите Load Schema — Tetiva отправит интроспекционный запрос и разложит результат на запросы, мутации и типы. Кнопка с круговой стрелкой перечитывает схему после деплоя, ошибка интроспекции показывается строкой рядом с кнопкой.
Если эндпоинт не отвечает на интроспекцию, схему можно взять из файла. Кнопка Attach schema выбирает .graphql, .graphqls, .gql или сохранённый результат интроспекции в .json — {"data": {"__schema": …}} или просто {"__schema": …}. Имя файла появится рядом с кнопкой, а крестик отцепит файл и снова загрузит схему по адресу. Пока файл прикреплён, схема берётся из него. Если файла нет на этом компьютере, например путь пришёл синхронизацией от коллеги, схема загрузится по адресу, а рядом появится подсказка File not found on this computer, using the URL; путь при этом останется в запросе. Файл должен лежать на этом компьютере и весить не больше 32 МБ: путь к сетевой папке или URL приложение не примет.
Два важных нюанса. Первый: в интроспекционный запрос уходят только включённые строки вкладки Headers — если схема закрыта токеном, положите Authorization именно туда, значения со вкладки Auth применяются при отправке самого запроса, но не при загрузке схемы. К интроспекции при этом прикладываются куки воркспейса для этого адреса — из того же хранилища, что и у HTTP-запросов, так что схема за сессионной кукой загружается после обычного запроса логина. Второй: интроспекция забирает корни Query и Mutation, поэтому подписки в список операций не попадают.
Operation Selector#
Селектор слева от кнопок показывает все операции схемы, сгруппированные на Queries и Mutations, с поиском по имени. Выбор операции делает три вещи сразу: подставляет имя в запрос, генерирует пример тела и заполняет переменные.
Пример строится по схеме на глубину три уровня вложенности: аргументы операции выносятся в объявления переменных ($id: ID!) и подставляются в вызов, скалярные и enum-поля выписываются целиком, вложенные объекты разворачиваются до предела глубины, а на последнем уровне остаются только скаляры. Для union- и interface-типов генерируются ветки ... on Type. Значения переменных заполняются заглушками по типам — перед отправкой замените их осмысленными.
Имя выбранной операции сохраняется в запросе и уходит на сервер как operationName — это важно, если в теле лежит несколько именованных операций.
Редактор запроса и переменных#
Редактор разделён по вертикали: сверху запрос, снизу сворачиваемая панель Variables с JSON. Обе части сохраняются вместе с запросом.
Когда схема загружена, в запросе работает автодополнение полей, типов и аргументов, а невалидные поля подчёркиваются линтером — обе функции берут данные из той же схемы, что показывает Operation Selector. Без загруженной схемы редактор остаётся обычным текстовым полем с подсветкой.
Cmd/Ctrl+Click по типу или полю открывает его во вкладке Schema. Пока клавиша зажата, токены подчёркиваются — видно, куда можно провалиться.
В тексте запроса и в переменных подставляются переменные окружения: {{tenant_id}} в JSON-переменных заменится перед отправкой так же, как в URL. См. окружения и переменные.
Вкладок у GraphQL-запроса семь: Query, Headers, Auth, Schema, Scripts, Docs и Examples. Docs хранит описание запроса в Markdown, см. описание запроса, а в Examples лежат примеры ответов.
Браузер схемы#
Вкладка Schema переключается между двумя режимами. Browse — интерактивный обход: список операций, детали выбранной (аргументы и возвращаемый тип), переход по полям к их типам. SDL — та же схема текстом, с поиском, который подсвечивает совпадения по мере ввода и считает их. В режиме Browse поле поиска фильтрует и список операций, и поля текущего типа. Cmd/Ctrl+F после клика по схеме или ответу ставит курсор в поиск этой панели.
Кнопка Open in Window выносит схему в отдельное окно — удобно, когда запрос длинный и переключаться на вкладку каждый раз дорого.
Отправка и ответ#
Cmd/Ctrl+Enter отправляет запрос, Cmd/Ctrl+S сохраняет его. Тело собирается как JSON с полями query, variables и operationName; Content-Type: application/json выставляется автоматически, к нему добавляются включённые заголовки и результат вкладки Auth — см. авторизацию.
Ответ разложен на вкладки Data, Errors, Headers и Tests. Разделение важно: GraphQL-сервер обычно отвечает HTTP 200 даже при ошибке резолвера, поэтому смотреть надо не только на статус — если в ответе есть массив errors, на вкладке Errors загорается индикатор. Вкладку Tests наполняют скрипты, а поиск по телу ответа описан в просмотре ответа.