Expondo endpoints públicos e privados
O GraphQL é tradicionalmente sobre expor um único endpoint, geralmente em https://mysite.com/graphql.
O Gato GraphQL expande essa noção, permitindo que exponhamos múltiplos endpoints personalizados, cada um adaptado a uma necessidade específica. Por exemplo, podemos expor endpoints:
/internale/public/apps/mobilee/apps/website/clientse/visitors/development,/staginge/production/teams/development,/teams/testinge/teams/marketing/clients/A,/clients/Beclients/Z- qualquer combinação deles
O Gato GraphQL também suporta Persisted Queries, que são endpoints onde a query GraphQL é predefinida e armazenada no servidor.
Este guia apresenta sugestões sobre como e quando usar cada endpoint.
Além de proteger os endpoints da sua API Gato GraphQL, recomendamos que você sempre reforce a segurança do seu site WordPress usando um plugin de segurança dedicado, como o WP Security Ninja.
Os endpoints são configurados por meio de uma Configuração de Schema, onde definimos:
- Definir o schema como público ou privado
- Habilitar elementos de dados "sensíveis"
- Aplicar namespacing ao schema
- Usar mutations aninhadas
- Definir cabeçalhos de resposta
- Conceder acesso aos elementos do schema via Access Control Lists
- Configurar cache HTTP
- Muitos outros
Se tivermos uma configuração que queremos aplicar a todos ou à maioria dos endpoints, podemos definir uma Configuração de Schema padrão.
Quando usar o endpoint único
O endpoint único é sempre público, exposto por padrão em /graphql.
O Gato GraphQL é gerenciado por meio de "módulos", cada um oferecendo uma funcionalidade ou extensão do schema GraphQL, e que podem ser habilitados e desabilitados conforme necessário.
Para reforçar a segurança da nossa API, é uma boa prática desabilitar os módulos que estendem o schema GraphQL (como os módulos "Posts", "Users", "Comments", "Blocks", etc.) quando não são necessários, para garantir que esses dados nunca sejam expostos em primeiro lugar.
Em particular, se a API não for destinada a mutar dados (ou seja, criar ou atualizar recursos), é uma boa prática desabilitar o módulo "Mutations". Ao fazer isso, todas as extensões que fornecem alguma mutation (como os módulos "Post Mutations", "Comment Mutations", etc.) serão desabilitadas, e essas mutations nunca serão expostas no schema GraphQL.
O endpoint único é recomendado quando:
- Precisamos recuperar dados para alimentar um único recurso, e
- O site WordPress não está acessível à Internet aberta (ou seja, está rodando em um laptop de desenvolvimento ou atrás de um firewall)
Este é o caso, por exemplo, para construir um site headless (usando Next.js, Gatsby, ou outros).
Quando usar endpoints personalizados públicos
Os endpoints personalizados são similares ao endpoint único, mas podemos ter muitos deles, cada um exposto sob sua própria URL graphql/{custom-endpoint-slug}/, com cada um tendo uma configuração diferente.
Os endpoints personalizados oferecem segurança por obscuridade, pois apenas o destinatário pretendido deve conhecer a existência do endpoint personalizado e sua URL.
Para reforçar a segurança da API, podemos usar a extensão Access Control para conceder acesso ao endpoint apenas quando:
- O usuário está logado (ou não)
- O usuário tem algum papel
- O usuário tem alguma capability
- O visitante vem de um IP permitido (via extensão Access Control: Visitor IP)
Cada endpoint personalizado pode ter sua própria Access Control List, sendo assim acessível apenas pelo seu usuário específico pretendido.
Os endpoints personalizados são recomendados quando precisamos gerenciar e personalizar os acessos à API, seja por diferentes aplicações, equipes, clientes ou qualquer outro.
Quando usar endpoints personalizados privados
O Gato GraphQL implementa endpoints personalizados via Custom Post Types (CPTs). Isso nos permite publicar o endpoint personalizado como privado (e também como protegido por senha), tornando o endpoint personalizado acessível apenas aos usuários logados que têm o direito de acessar aquele post personalizado, e mais ninguém.
Este método é recomendado quando o endpoint GraphQL é destinado a ser usado apenas pelo administrador do site (como quando se usa GraphQL para executar tarefas de administração). Ao bloquear completamente o acesso ao endpoint por visitantes externos, estaremos reforçando a segurança do site.
Quando usar Persisted Queries públicas
As persisted queries são endpoints, cada um com sua própria URL, mas a query GraphQL já está definida no lado do servidor, portanto a resposta também é predefinida (pode ser tornada dinâmica definindo variáveis, a serem satisfeitas por parâmetros de URL).
As persisted queries são similares aos endpoints REST, mas usamos a linguagem GraphQL para compor a query, e podemos publicá-la diretamente do wp-admin. Não é necessário implantar nenhum código PHP para publicar uma persisted query.
Como as persisted queries não requerem a passagem da query GraphQL no corpo da requisição, elas são naturalmente adequadas para serem acessadas via GET em vez de POST.
(O endpoint único e os endpoints personalizados também podem ser acessados via GET adicionando o parâmetro ?query={ GraphQL query } ao endpoint.)
Podemos nos beneficiar disso e tornar a API mais rápida por meio do Cache HTTP padrão, fazendo cache da resposta GraphQL no lado do cliente ou em etapas intermediárias entre o cliente e o servidor (como uma CDN).
Isso é realizado por meio da extensão Cache Control, que calcula e emite automaticamente o valor max-age da resposta com base nos campos e diretivas presentes na query.
É recomendado usar persisted queries sempre que possível, pois elas aumentam substancialmente a segurança dos nossos sites.
Isso ocorre porque todos os dados que precisam ser disponibilizados para nossa aplicação já podem ser expostos via persisted queries. Então, podemos evitar expor o endpoint único GraphQL (ou qualquer endpoint personalizado), eliminando assim a chance de que usuários possam acessar dados privados que deixamos expostos (por engano ou de outra forma).
Quando usar Persisted Queries privadas
Semelhante aos endpoints personalizados, as persisted queries são CPTs, portanto podemos publicá-las como private (ou protegidas por senha), tornando-as acessíveis apenas aos usuários logados que têm o direito de acessá-las, e mais ninguém.
É recomendado usá-las sempre que a query for destinada apenas ao uso interno, como ao pesquisar dados do WordPress para uso próprio.