Persisted Queries
Используйте GraphQL queries для создания заранее определённых эндпоинтов, как в REST, получая преимущества обоих API.
Описание
С REST вы создаёте несколько эндпоинтов, каждый из которых возвращает заранее определённый набор данных.
| Преимущества | Недостатки |
|---|---|
| ✅ Просто в использовании | ❌ Создавать все эндпоинты утомительно |
✅ Доступ через GET или POST | ❌ Проект может столкнуться с узкими местами в ожидании готовности эндпоинтов |
| ✅ Можно кешировать на сервере или CDN | ❌ Создание документации обязательно |
| ✅ Безопасно: раскрываются только предусмотренные данные | ❌ Может работать медленно (особенно для мобильных приложений), так как приложению может потребоваться несколько запросов для получения всех данных |
С GraphQL вы отправляете любой запрос на единственный эндпоинт, который возвращает именно запрошенные данные.
| Преимущества | Недостатки |
|---|---|
| ✅ Нет проблем с лишней или недостаточной выборкой данных | ❌ Доступ только через POST |
| ✅ Может работать быстро, так как все данные получаются в одном запросе | ❌ Нельзя кешировать на сервере или CDN, что делает его медленнее и дороже, чем могло бы быть |
| ✅ Позволяет быстро итерировать проект | ❌ Может потребоваться изобретать велосипед, например, для загрузки файлов или кеширования |
| ✅ Может быть самодокументируемым | ❌ Необходимо справляться с дополнительными сложностями, например, с проблемой N+1 |
| ✅ Предоставляет редактор для queries (GraphiQL), упрощающий задачу |
Persisted queries объединяют эти два подхода:
- Используют GraphQL для создания и выполнения queries
- Но вместо того чтобы раскрывать единственный эндпоинт, каждый заранее определённый запрос доступен под собственным эндпоинтом
Таким образом, мы получаем несколько эндпоинтов с предопределёнными данными, как в REST, но созданных с помощью GraphQL, сочетая преимущества обоих подходов и избегая их недостатков:
| Преимущества | Недостатки |
|---|---|
✅ Доступ через GET или POST | |
| ✅ Можно кешировать на сервере или CDN | |
| ✅ Безопасно: раскрываются только предусмотренные данные | |
| ✅ Нет проблем с лишней или недостаточной выборкой данных | |
| ✅ Может работать быстро, так как все данные получаются в одном запросе | POST |
| ✅ Позволяет быстро итерировать проект | |
| ✅ Может быть самодокументируемым | |
| ✅ Предоставляет редактор для queries (GraphiQL), упрощающий задачу |
Выполнение Persisted Query
После публикации persisted query её можно выполнить по её permalink.
Persisted query может быть выполнена непосредственно в браузере, так как доступ к ней осуществляется через GET, и вы получите запрошенные данные в формате JSON:
Создание Persisted Query
При нажатии на ссылку Persisted Queries в меню отображается список всех созданных persisted queries:
Persisted query — это пользовательский тип записи (CPT). Чтобы создать новую persisted query, нажмите кнопку «Добавить новую GraphQL persisted query», откроется редактор WordPress:
Основным элементом является клиент GraphiQL, который по умолчанию поставляется с Explorer. Щелчок по полям на левой боковой панели добавляет их в запрос, а нажатие кнопки «Run» выполняет запрос:
Когда запрос готов, опубликуйте его, и его permalink станет эндпоинтом. Ссылка на эндпоинт (и на исходный код) отображается на боковой панели «Обзор эндпоинта Persisted Query»:
Добавив ?view=source к permalink, вы увидите persisted query и её конфигурацию (при условии, что пользователь вошёл в систему и роль пользователя имеет доступ к ней):
По умолчанию эндпоинт persisted query имеет путь /graphql-query/, и это значение можно настроить через Настройки:
Конфигурация схемы
Определение того, какие элементы содержит схема и какой доступ к ней будут иметь пользователи, задаётся в конфигурации схемы.
Поэтому необходимо создать конфигурацию схемы, а затем выбрать её из выпадающего списка:
Организация Persisted Queries по категориям
На боковой панели «Категории эндпоинтов» можно добавлять категории для удобного управления Persisted Query:
Например, можно создавать категории для управления эндпоинтами по клиенту, приложению или любому другому необходимому признаку:
В списке Persisted Queries можно видеть их категории, а нажатие на любую ссылку категории или использование фильтра вверху покажет только записи этой категории:
Приватные persisted queries
Установив статус Persisted Query как private, доступ к эндпоинту получит только администратор. Это предотвращает непреднамеренный доступ к данным со стороны пользователей, которые не должны его иметь.
Например, можно создавать приватные Persisted Queries для управления приложением, например для получения данных с целью создания отчётов с метриками.
Persisted queries, защищённые паролем
Если вы создаёте Persisted Query для конкретного клиента, можно назначить ей пароль, чтобы обеспечить дополнительный уровень безопасности и гарантировать, что только этот клиент получит доступ к эндпоинту.
При первом обращении к persisted query, защищённой паролем, пользователь увидит экран с запросом пароля:
Только после ввода и проверки пароля пользователь получит доступ к нужному эндпоинту.
Динамические persisted queries с помощью параметров URL
Значение каждой переменной можно задать через параметр URL (с именем переменной) при выполнении persisted query. Если включена опция «Переопределяют ли параметры URL переменные?», параметр URL будет иметь приоритет. В противном случае приоритет будет иметь значение, определённое в словаре переменных (если оно задано).
Например, в этом запросе количество результатов контролируется переменной $limit со значением по умолчанию 3:
При выполнении этой persisted query передача ?limit=5 выполнит запрос, возвращающий 5 результатов:
