Persisted Queries
Use queries GraphQL para criar endpoints pré-definidos como no REST, obtendo os benefícios de ambas as APIs.
Descrição
Com REST, você cria múltiplos endpoints, cada um retornando um conjunto pré-definido de dados.
| Vantagens | Desvantagens |
|---|---|
| ✅ É simples | ❌ É tedioso criar todos os endpoints |
✅ Acessível via GET ou POST | ❌ Um projeto pode enfrentar gargalos aguardando os endpoints ficarem prontos |
| ✅ Pode ser armazenado em cache no servidor ou CDN | ❌ Produzir documentação é obrigatório |
| ✅ É seguro: apenas os dados previstos são expostos | ❌ Pode ser lento (principalmente para apps móveis), pois a aplicação pode precisar de várias requisições para recuperar todos os dados |
Com GraphQL, você envia qualquer query para um único endpoint, que retorna exatamente os dados solicitados.
| Vantagens | Desvantagens |
|---|---|
| ✅ Sem sub/sobre-busca de dados | ❌ Acessível apenas via POST |
| ✅ Pode ser rápido, pois todos os dados são recuperados em uma única requisição | ❌ Não pode ser armazenado em cache no servidor ou CDN, tornando-o mais lento e mais caro do que poderia ser |
| ✅ Permite iteração rápida do projeto | ❌ Pode exigir reinventar a roda, como para upload de arquivos ou cache |
| ✅ Pode ser auto-documentado | ❌ Precisa lidar com complexidades adicionais, como o problema N+1 |
| ✅ Fornece um editor para a query (GraphiQL) que simplifica a tarefa |
As queries persistidas combinam essas 2 abordagens:
- Usam GraphQL para criar e resolver queries
- Mas em vez de expor um único endpoint, expõem cada query pré-definida sob seu próprio endpoint
Assim, obtemos múltiplos endpoints com dados pré-definidos, como no REST, mas criados com GraphQL, obtendo as vantagens de cada um e evitando suas desvantagens:
| Vantagens | Desvantagens |
|---|---|
✅ Acessível via GET ou POST | |
| ✅ Pode ser armazenado em cache no servidor ou CDN | |
| ✅ É seguro: apenas os dados previstos são expostos | |
| ✅ Sem sub/sobre-busca de dados | |
| ✅ Pode ser rápido, pois todos os dados são recuperados em uma única requisição | POST |
| ✅ Permite iteração rápida do projeto | |
| ✅ Pode ser auto-documentado | |
| ✅ Fornece um editor para a query (GraphiQL) que simplifica a tarefa |
Executando a Query Persistida
Após a query persistida ser publicada, podemos executá-la via seu permalink.
A query persistida pode ser executada diretamente no navegador, pois é acessível via GET, e obteremos os dados solicitados no formato JSON:
Criando uma Query Persistida
Ao clicar no link Persisted Queries no menu, é exibida a lista de todas as queries persistidas criadas:
Uma query persistida é um custom post type (CPT). Para criar uma nova query persistida, clique no botão "Add New GraphQL persisted query", que abrirá o editor do WordPress:
O input principal é o cliente GraphiQL, que vem com o Explorer por padrão. Clicar nos campos no painel lateral esquerdo os adiciona à query, e clicar no botão "Run" executa a query:
Quando a query estiver pronta, publique-a, e seu permalink se torna seu endpoint. O link para o endpoint (e para o código-fonte) é exibido no painel lateral "Persisted Query Endpoint Overview":
Ao adicionar ?view=source ao permalink, serão exibidas a query persistida e sua configuração (desde que o usuário esteja autenticado e seu perfil tenha acesso):
Por padrão, o endpoint da query persistida tem o caminho /graphql-query/, e esse valor é configurável nas Configurações:
Configuração do schema
A definição de quais elementos o schema contém, e qual acesso os usuários terão a ele, é feita na configuração do schema.
Portanto, precisamos criar uma configuração de schema e selecioná-la no menu suspenso:
Organizando Queries Persistidas por Categoria
No painel lateral "Endpoint categories" podemos adicionar categorias para ajudar a gerenciar a Query Persistida:
Por exemplo, podemos criar categorias para gerenciar endpoints por cliente, aplicação ou qualquer outra informação necessária:
Na lista de Queries Persistidas, podemos visualizar suas categorias e, ao clicar em qualquer link de categoria ou usar o filtro no topo, serão exibidas apenas as entradas daquela categoria:
Queries persistidas privadas
Ao definir o status da Query Persistida como private, o endpoint só pode ser acessado pelo usuário administrador. Isso evita que nossos dados sejam compartilhados inadvertidamente com usuários que não deveriam ter acesso a eles.
Por exemplo, podemos criar Queries Persistidas privadas para ajudar a gerenciar a aplicação, como recuperar dados para criar relatórios com nossas métricas.
Queries persistidas protegidas por senha
Se criarmos uma Query Persistida para um cliente específico, podemos atribuir uma senha a ela, para fornecer um nível adicional de segurança e garantir que apenas aquele cliente acesse o endpoint.
Ao acessar pela primeira vez uma query persistida protegida por senha, nos deparamos com uma tela solicitando a senha:
Somente após a senha ser fornecida e validada, o usuário terá acesso ao endpoint pretendido.
Tornando a query persistida dinâmica via parâmetros de URL
O valor de cada variável pode ser definido via um parâmetro de URL (com o nome da variável) ao executar a query persistida. Se a opção "Os parâmetros de URL substituem as variáveis?" estiver habilitada, o parâmetro de URL terá prioridade. Caso contrário, o valor definido no dicionário de variáveis terá prioridade (se houver).
Por exemplo, nesta query, o número de resultados é controlado pela variável $limit, com um valor padrão de 3:
Ao executar esta query persistida, passar ?limit=5 executará a query retornando 5 resultados em vez disso:
