Публичные и приватные эндпоинты
GraphQL традиционно предполагает один эндпоинт, обычно по адресу https://mysite.com/graphql.
Gato GraphQL расширяет эту концепцию, позволяя создавать несколько кастомных эндпоинтов, каждый из которых настроен под конкретную задачу. Например, можно создать эндпоинты:
/internalи/public/apps/mobileи/apps/website/clientsи/visitors/development,/stagingи/production/teams/development,/teams/testingи/teams/marketing/clients/A,/clients/Bиclients/Z- любые их комбинации
Gato GraphQL также поддерживает Persisted Queries — эндпоинты с заранее определёнными и сохранёнными на сервере GraphQL queries.
В этом руководстве представлены рекомендации по выбору и использованию каждого типа эндпоинта.
Помимо защиты эндпоинтов API Gato GraphQL, мы рекомендуем всегда усиливать безопасность вашего сайта WordPress с помощью специального плагина безопасности, например WP Security Ninja.
Эндпоинты настраиваются через Конфигурацию схемы, где можно задать:
- Публичность или приватность схемы
- Включение «чувствительных» элементов данных
- Пространство имён схемы
- Использование вложенных мутаций
- Определение заголовков ответа
- Управление доступом к элементам схемы через списки контроля доступа
- Настройку HTTP-кэширования
- И многое другое
Если нужно применить одну конфигурацию ко всем или большинству эндпоинтов, можно задать конфигурацию схемы по умолчанию.
Когда использовать единый эндпоинт
Единый эндпоинт всегда публичен и доступен по умолчанию по адресу /graphql.
Gato GraphQL управляется через «модули», каждый из которых предоставляет определённую функциональность или расширяет схему GraphQL, и которые можно включать и отключать по необходимости.
Для повышения безопасности API рекомендуется отключать модули, расширяющие схему GraphQL (например, «Posts», «Users», «Comments», «Blocks» и т.д.), когда они не нужны — это гарантирует, что данные вообще не будут доступны.
В частности, если API не предназначен для изменения данных (то есть создания или обновления ресурсов), рекомендуется отключить модуль «Mutations». Это автоматически отключит все расширения, предоставляющие мутации (например, «Post Mutations», «Comment Mutations» и т.д.), и эти мутации никогда не появятся в схеме GraphQL.
Единый эндпоинт рекомендуется использовать, когда:
- Нужно получать данные для одной функции, и
- Сайт WordPress недоступен из открытого интернета (например, работает на локальном компьютере разработчика или за файрволом)
Это актуально, например, при создании headless-сайтов (с использованием Next.js, Gatsby или других фреймворков).
Когда использовать публичные кастомные эндпоинты
Кастомные эндпоинты похожи на единый эндпоинт, но их может быть несколько — каждый со своим URL graphql/{custom-endpoint-slug}/ и собственной конфигурацией.
Кастомные эндпоинты обеспечивают безопасность через неизвестность: только предполагаемые пользователи знают о существовании конкретного эндпоинта и его URL.
Для усиления безопасности API можно использовать расширение Access Control, чтобы разрешить доступ к эндпоинту только при выполнении условий:
- Пользователь авторизован (или нет)
- Пользователь имеет определённую роль
- Пользователь обладает определённым разрешением
- Посетитель приходит с разрешённого IP-адреса (через расширение Access Control: Visitor IP)
У каждого кастомного эндпоинта может быть свой список контроля доступа, делающий его доступным только для конкретных пользователей.
Кастомные эндпоинты рекомендуются, когда нужно управлять и настраивать доступ к API для разных приложений, команд, клиентов или других категорий пользователей.
Когда использовать приватные кастомные эндпоинты
Gato GraphQL реализует кастомные эндпоинты через Custom Post Types (CPT). Это позволяет опубликовать кастомный эндпоинт как приватный (или защищённый паролем), делая его доступным только для авторизованных пользователей с правом доступа к этому типу записи — и никому больше.
Этот метод рекомендуется, когда GraphQL-эндпоинт предназначен исключительно для администратора сайта (например, для выполнения административных задач через GraphQL). Полная блокировка доступа для внешних посетителей существенно повышает безопасность сайта.
Когда использовать публичные Persisted Queries
Persisted queries — это эндпоинты с собственным URL, в которых GraphQL query уже определён на стороне сервера, а значит, ответ тоже предопределён (он может быть динамическим за счёт переменных, передаваемых через параметры URL).
Persisted queries похожи на REST-эндпоинты, но для формирования запроса используется язык GraphQL, а публикация выполняется прямо из wp-admin — без необходимости разворачивать PHP-код.
Поскольку persisted queries не требуют передачи GraphQL query в теле запроса, они естественным образом подходят для доступа через GET вместо POST.
(К единому и кастомным эндпоинтам тоже можно обращаться через GET, добавив параметр ?query={ GraphQL query } к URL эндпоинта.)
Это позволяет ускорить работу API с помощью стандартного HTTP-кэширования: GraphQL-ответы кэшируются на стороне клиента или на промежуточных уровнях между клиентом и сервером (например, на CDN).
Это реализуется через расширение Cache Control, которое автоматически вычисляет и устанавливает значение max-age ответа на основе полей и директив, присутствующих в запросе.
Рекомендуется использовать persisted queries везде, где это возможно, поскольку они существенно повышают безопасность сайтов.
Это объясняется тем, что все данные, необходимые приложению, уже доступны через persisted queries. В таком случае можно отказаться от единого GraphQL-эндпоинта (и любых кастомных эндпоинтов), устраняя риск того, что пользователи получат доступ к случайно открытым приватным данным.
Когда использовать приватные Persisted Queries
Как и кастомные эндпоинты, persisted queries являются CPT, поэтому их можно публиковать как приватные (или защищённые паролем), делая их доступными только для авторизованных пользователей с правом доступа — и никому больше.
Их рекомендуется использовать, когда запрос предназначен исключительно для внутреннего использования, например для поиска данных WordPress в собственных целях.