Assinar

O que você está procurando?

Aperte Enter para buscar ou ESC para fechar

GraphQL e WPGraphQL

GraphQL é uma linguagem de consulta e uma especificação para APIs que permite que o cliente descreva exatamente quais dados deseja receber.

Em vez de existir apenas uma resposta previamente definida pelo servidor, como normalmente acontece em APIs baseadas em endpoints, uma API GraphQL publica um schema descrevendo quais tipos de dados existem, quais campos esses tipos possuem e como eles se relacionam.

A aplicação cliente pode então navegar por esse schema e solicitar apenas os campos necessários.

No WordPress, essa arquitetura pode ser implementada através do WPGraphQL, um plugin gratuito e open source que adiciona ao WordPress um schema GraphQL extensível e uma API pela qual posts, páginas, usuários, taxonomias e outros dados podem ser consultados ou modificados.

O que é GraphQL?

GraphQL foi criado originalmente no Facebook em 2012 e disponibilizado como projeto open source em 2015. Desde 2019, o projeto está sob a GraphQL Foundation, hospedada pela Linux Foundation.

Apesar do nome, GraphQL não é um banco de dados.

Também não é um ORM, uma biblioteca específica de JavaScript ou um substituto para REST.

GraphQL é, essencialmente, uma especificação para descrever um schema de dados e uma linguagem através da qual clientes podem consultar esse schema. Ele pode ser implementado em diferentes linguagens de programação e trabalhar sobre praticamente qualquer fonte de dados.

Uma implementação poderia consultar:

  • um banco MySQL;
  • PostgreSQL;
  • uma API externa;
  • arquivos;
  • serviços internos;
  • diferentes bancos simultaneamente;
  • ou qualquer outra fonte que o servidor saiba resolver.

No caso do WPGraphQL, essa fonte de dados e camada de aplicação é o WordPress.

O GraphQL enxerga os dados como um grafo

Uma das diferenças conceituais importantes está na forma como os dados são representados.

Imagine um post do WordPress.

Esse post possui um autor.

O autor possui um avatar.

O post também pode possuir categorias, tags, comentários, uma imagem destacada e outros relacionamentos.

Podemos representar isso conceitualmente assim:

Post
├── Autor
│   └── Avatar
├── Imagem destacada
├── Categorias
├── Tags
└── Comentários

É daí que vem o “Graph” do nome GraphQL.

Os dados são tratados como objetos relacionados que podem ser percorridos através de seus campos.

Isso não significa que exista um graph database por trás da aplicação.

O WordPress, por exemplo, continua utilizando seu banco de dados normalmente.

O grafo é a maneira como a API representa e disponibiliza as relações entre os dados.

O schema é o contrato da API

No centro de qualquer API GraphQL existe o schema.

Ele descreve tudo o que pode ser consultado através daquela API.

Um schema extremamente simples poderia ser:

type Query {
  hello: String
}

Nesse caso, o servidor informa que existe um campo chamado:

hello

e que ele retorna:

String

O cliente poderia então enviar:

{
  hello
}

e receber algo como:

{
  "data": {
    "hello": "Olá, mundo!"
  }
}

O schema funciona como um contrato entre cliente e servidor.

O servidor determina o que pode ser solicitado.

O cliente determina quais desses dados deseja receber.

GraphQL possui um sistema de tipos

O schema GraphQL é fortemente tipado.

Cada campo precisa declarar qual tipo de dado pode retornar.

GraphQL possui alguns tipos escalares básicos, como:

String
Int
Float
Boolean
ID

Também podemos criar tipos mais complexos.

Por exemplo:

type Post {
  id: ID!
  title: String!
  date: String
  author: User
}

Nesse schema, Post é um tipo.

Ele possui campos como:

id
title
date
author

Mas author não retorna uma string.

Ele retorna outro tipo:

User

Isso permite continuar navegando pelo grafo:

{
  post {
    title
    author {
      name
    }
  }
}

Essa estrutura tipada é uma das características mais importantes do GraphQL.

O cliente consegue conhecer antecipadamente quais campos existem, quais argumentos aceitam e quais tipos de valores retornam.

Queries são utilizadas para consultar dados

A operação mais comum em GraphQL é a query.

Uma query descreve os dados que o cliente deseja receber.

No WPGraphQL, por exemplo:

query {
  posts {
    nodes {
      id
      title
    }
  }
}

solicita posts, mas apenas dois campos de cada post:

id
title

Uma possível resposta seria:

{
  "data": {
    "posts": {
      "nodes": [
        {
          "id": "cG9zdDox",
          "title": "Olá, mundo!"
        }
      ]
    }
  }
}

O formato da resposta acompanha aproximadamente a estrutura solicitada na query. Essa previsibilidade é uma característica central do GraphQL.

É possível atravessar relacionamentos na mesma query

Uma query também pode solicitar dados relacionados.

Por exemplo:

query {
  posts(first: 5) {
    nodes {
      title
      date
      author {
        node {
          name
          avatar {
            url
          }
        }
      }
    }
  }
}

Nesse caso, estamos pedindo:

Post
├── título
├── data
└── autor
    ├── nome
    └── avatar
        └── URL

O cliente descreve a estrutura que deseja e o servidor resolve esses relacionamentos.

Esse modelo é particularmente útil para interfaces nas quais diferentes componentes precisam combinar dados provenientes de vários objetos relacionados.

Arguments modificam o resultado de um campo

Campos GraphQL podem aceitar argumentos.

Por exemplo:

query {
  posts(first: 10) {
    nodes {
      title
    }
  }
}

Aqui:

first: 10

é um argumento.

Ele informa que queremos os primeiros dez itens daquela conexão.

Outros campos podem aceitar argumentos para filtragem, ordenação, busca ou identificação de objetos.

No WPGraphQL, os argumentos disponíveis dependem do tipo e do campo que está sendo consultado.

Variables evitam montar queries dinamicamente

Valores dinâmicos normalmente não devem ser inseridos diretamente dentro da string da query.

GraphQL possui variables para isso.

Por exemplo:

query GetPosts($quantity: Int!) {
  posts(first: $quantity) {
    nodes {
      id
      title
    }
  }
}

As variáveis podem ser enviadas separadamente:

{
  "quantity": 10
}

Isso deixa a operação mais previsível, facilita reutilização e evita a necessidade de construir strings GraphQL dinamicamente. A própria documentação do WPGraphQL recomenda variables em vez de interpolação de strings.

Fragments permitem reutilizar conjuntos de campos

Imagine que várias queries precisem sempre solicitar:

id
title
date
uri

Podemos criar um fragment:

fragment PostSummary on Post {
  id
  title
  date
  uri
}

E utilizá-lo:

query {
  posts {
    nodes {
      ...PostSummary
    }
  }
}

Fragments reduzem repetição e ajudam aplicações maiores a compartilhar definições de dados entre componentes.

Mutations modificam dados

Queries são utilizadas para leitura.

Quando a intenção é modificar dados, GraphQL utiliza mutations.

No WPGraphQL, uma mutation para criar um post poderia se parecer com:

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    post {
      id
      title
    }
  }
}

Com os dados enviados separadamente através de uma variável:

{
  "input": {
    "title": "Meu novo artigo",
    "status": "DRAFT"
  }
}

Mutations podem representar operações como:

  • criar conteúdo;
  • atualizar conteúdo;
  • excluir conteúdo;
  • modificar usuários;
  • alterar configurações;
  • ou executar operações adicionadas por plugins.

No WPGraphQL, a maior parte das mutations que modifica conteúdo exige autenticação e as capabilities adequadas do usuário.

Resolvers transformam campos em dados

Declarar que um campo existe no schema não é suficiente.

Alguém precisa descobrir qual valor aquele campo deve retornar.

Essa responsabilidade pertence aos resolvers.

Um resolver é uma função executada quando determinado campo é solicitado.

Por exemplo, podemos adicionar ao WPGraphQL:

add_action(
    'graphql_register_types',
    function () {
        register_graphql_field(
            'RootQuery',
            'hello',
            [
                'type'    => 'String',
                'resolve' => function () {
                    return 'Olá, mundo!';
                },
            ]
        );
    }
);

Isso adiciona ao schema:

hello: String

Quando uma query solicitar:

{
  hello
}

o resolver será executado e retornará:

{
  "data": {
    "hello": "Olá, mundo!"
  }
}

Resolvers existem em implementações GraphQL em geral. O WPGraphQL fornece suas próprias APIs PHP para registrá-los e integrá-los ao WordPress.

E o que é exatamente o WPGraphQL?

O WPGraphQL é um plugin WordPress que implementa uma API GraphQL sobre o WordPress.

Depois de instalado, ele registra um schema contendo tipos e campos que representam diversos objetos conhecidos do WordPress, como posts, páginas, usuários, comentários, menus, taxonomias, mídias e configurações.

É importante diferenciar:

GraphQL

é a linguagem, especificação e modelo de execução.

WPGraphQL

é uma implementação dessa tecnologia integrada ao WordPress.

Portanto, WPGraphQL não é sinônimo de GraphQL.

Existem APIs GraphQL em diversas outras plataformas e linguagens.

WPGraphQL não faz parte do WordPress Core

Ao contrário da REST API, o WPGraphQL não é uma API nativa do WordPress Core.

Ele precisa ser instalado como plugin.

Uma vez ativado, adiciona ao site uma API GraphQL e um schema que pode ser estendido tanto pelo próprio WPGraphQL quanto por outros plugins e código personalizado.

Isso é uma diferença arquitetural importante.

Uma instalação WordPress possui a REST API mesmo sem plugins adicionais.

Para disponibilizar GraphQL através do WPGraphQL, essa camada precisa estar instalada e mantida no projeto.

Qual é o endpoint do WPGraphQL?

Com uma estrutura normal de links permanentes, o WPGraphQL disponibiliza por padrão:

/graphql

Assim, um site poderia receber requisições em:

https://exemplo.com/graphql

Quando o WordPress utiliza a estrutura de permalinks simples, o endpoint pode aparecer como:

/index.php?graphql

WPGraphQL aceita requisições HTTP contendo a operação GraphQL que deverá ser executada.

Isso evidencia outra diferença conceitual importante em relação a APIs orientadas a recursos.

Em vez de precisar de URLs diferentes como:

/posts
/users
/categories
/comments

o GraphQL normalmente possui um ponto de entrada pelo qual diferentes operações são enviadas.

A estrutura dos dados desejados está na própria operação GraphQL.

Como posts aparecem no schema?

Depois que WPGraphQL está ativo, podemos consultar posts com:

query {
  posts {
    nodes {
      id
      title
      date
      uri
    }
  }
}

Podemos solicitar um post específico através dos campos disponibilizados pelo schema ou navegar para outros objetos através de suas relações.

O importante é que não estamos consultando diretamente:

wp_posts

nem executando manualmente:

WP_Query

O cliente interage com o schema GraphQL.

O WPGraphQL fica responsável por traduzir essa operação para os mecanismos apropriados do WordPress.

Connections representam coleções e relacionamentos

WPGraphQL utiliza o padrão de connections inspirado na especificação Relay para representar relações e coleções paginadas.

É por isso que muitas queries possuem estruturas como:

posts {
  nodes {
    id
    title
  }
}

nodes fornece acesso direto aos objetos.

Também podemos utilizar:

posts {
  edges {
    cursor
    node {
      id
      title
    }
  }
}

Nesse caso temos uma estrutura intermediária chamada:

edge

Ela pode carregar informações relativas à própria conexão, como o cursor utilizado para paginação.

Conceitualmente:

Connection
├── Edge
│   ├── cursor
│   └── Node
│       └── Post

Quando não precisamos de informações da conexão, nodes geralmente produz uma query mais simples.

A paginação é baseada em cursores

Connections também permitem paginação através de cursores.

Uma primeira consulta poderia solicitar:

query {
  posts(first: 10) {
    nodes {
      id
      title
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

A resposta pode informar:

hasNextPage
endCursor

A próxima consulta utiliza esse cursor:

query GetMorePosts($after: String) {
  posts(first: 10, after: $after) {
    nodes {
      id
      title
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Em vez de pensar apenas em:

página 1
página 2
página 3

o cliente pode pedir os itens que aparecem depois de determinado cursor.

id e databaseId não significam a mesma coisa

Esse detalhe costuma causar confusão em quem começa a utilizar WPGraphQL.

Um post pode retornar:

{
  id
  databaseId
}

databaseId representa o ID tradicional utilizado pelo WordPress.

Por exemplo:

123

Já id é um Global ID do GraphQL.

WPGraphQL gera IDs globais opacos que identificam nós dentro do grafo independentemente do tipo específico de objeto.

Por exemplo:

cG9zdDoxMjM=

O cliente GraphQL normalmente deve tratar esse valor como um identificador opaco, e não depender de sua representação interna.

Bibliotecas como Apollo Client e Relay também podem utilizar esses identificadores para normalização e cache dos objetos.

Custom Post Types não aparecem automaticamente

Ter um Custom Post Type registrado no WordPress não significa que ele será automaticamente exposto pelo WPGraphQL.

Ele precisa ser configurado para isso.

Por exemplo:

register_post_type(
    'book',
    [
        'public'               => true,
        'show_in_graphql'      => true,
        'graphql_single_name'  => 'book',
        'graphql_plural_name'  => 'books',
    ]
);

show_in_graphql informa que aquele tipo deve fazer parte do schema.

Os campos:

graphql_single_name
graphql_plural_name

definem como ele será representado no GraphQL.

Isso é importante porque a exposição de dados através da API é uma decisão explícita.

Taxonomias também podem ser adicionadas ao schema

O mesmo princípio se aplica a taxonomias personalizadas.

Elas também podem utilizar:

'show_in_graphql'     => true,
'graphql_single_name' => 'genre',
'graphql_plural_name' => 'genres',

para serem disponibilizadas através do schema.

Campos personalizados podem ser adicionados ao schema

WPGraphQL possui APIs próprias para estender o schema.

Um dos exemplos mais simples é:

register_graphql_field()

Podemos adicionar um campo a Post:

add_action(
    'graphql_register_types',
    function () {
        register_graphql_field(
            'Post',
            'readingTime',
            [
                'type'    => 'Int',
                'resolve' => function ( $post ) {
                    return 5;
                },
            ]
        );
    }
);

A partir daí:

query {
  posts {
    nodes {
      title
      readingTime
    }
  }
}

passaria a ser uma operação válida.

Também é possível registrar tipos inteiros com APIs como:

register_graphql_object_type()

Isso permite que plugins criem estruturas GraphQL próprias em vez de simplesmente adicionar campos aos tipos existentes.

Plugins podem possuir integrações específicas com WPGraphQL

Instalar WPGraphQL não significa automaticamente que todos os dados de todos os plugins do site aparecerão no schema.

Um plugin precisa fornecer suporte ao WPGraphQL, ou outra extensão precisa fazer essa integração.

Advanced Custom Fields, por exemplo, possui a extensão WPGraphQL for ACF, que permite expor field groups e campos ACF através do schema GraphQL.

Isso é importante ao planejar uma arquitetura headless.

É necessário verificar se os plugins utilizados pelo projeto expõem os dados necessários através de GraphQL ou se será preciso desenvolver essa integração.

WPGraphQL possui uma camada de loaders

Uma query GraphQL pode atravessar muitos relacionamentos.

Imagine:

10 posts
→ autores
→ avatars
→ posts de cada autor

Se cada objeto fosse carregado individualmente assim que encontrado, poderíamos criar o conhecido problema de N+1 queries.

WPGraphQL utiliza uma arquitetura de loaders para reduzir esse problema.

Em vez de obrigatoriamente buscar um objeto imediatamente, identificadores podem ser acumulados e recursos relacionados carregados em conjunto.

O fluxo simplificado pode ser entendido como:

Query GraphQL
      ↓
Resolvers
      ↓
Loaders
      ↓
Model Layer
      ↓
WordPress
      ↓
Banco de dados / outras fontes

Isso não significa que qualquer query GraphQL será automaticamente rápida.

Uma query profundamente aninhada ou que solicite muitos campos ainda pode ser cara.

Mas essa arquitetura permite que WPGraphQL otimize diversos tipos de carregamento de dados relacionados.

Pedir somente os dados necessários continua sendo importante

Uma das principais vantagens do GraphQL é poder selecionar campos.

Mas essa flexibilidade pode ser mal utilizada.

Uma query como:

posts {
  nodes {
    author {
      node {
        posts {
          nodes {
            author {
              node {
                posts {
                  nodes {
                    title
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

é tecnicamente possível em determinados schemas, mas pode exigir bastante processamento.

A documentação do WPGraphQL recomenda solicitar apenas os dados realmente necessários e evitar aninhamentos excessivos de connections.

GraphQL oferece flexibilidade ao cliente.

Essa flexibilidade não elimina a necessidade de pensar em performance.

Como funciona autenticação e autorização?

GraphQL, enquanto especificação, não determina como uma aplicação deve autenticar usuários.

Isso é responsabilidade da implementação.

No WPGraphQL, autenticação e autorização se apoiam no sistema existente do WordPress.

É importante novamente separar dois conceitos:

Autenticação

determina quem está fazendo a requisição.

Autorização

determina quais dados e operações aquele usuário pode acessar.

WPGraphQL utiliza usuários e capabilities do WordPress para controlar o acesso a informações privadas e operações protegidas.

Por exemplo, um usuário pode estar autenticado, mas não possuir permissão para publicar um post.

Nesse caso, uma mutation que exige essa capability deve ser recusada.

Conteúdo público continua público

Assim como acontece no frontend normal do WordPress, conteúdo publicamente acessível pode ser consultado sem autenticação.

Isso não significa que todos os campos de todos os objetos sejam públicos.

Um usuário com posts publicados, por exemplo, pode ser uma entidade pública no schema, enquanto campos sensíveis associados àquela conta continuam restritos.

A camada de autorização é responsável por decidir o que pode ser resolvido para cada requisição.

Introspection permite consultar o próprio schema

Uma característica especialmente interessante de GraphQL é a introspection.

O próprio schema pode ser consultado.

Podemos descobrir:

  • quais tipos existem;
  • quais campos pertencem a cada tipo;
  • quais argumentos um campo aceita;
  • quais tipos são retornados;
  • quais enums existem;
  • quais queries e mutations estão disponíveis.

É essa capacidade que permite ferramentas de desenvolvimento oferecerem autocomplete e documentação automática.

WPGraphQL suporta introspection, embora atualmente desabilite introspection pública por padrão por motivos de segurança. Ela pode ser habilitada nas configurações quando necessário.

GraphiQL ajuda a explorar a API

WPGraphQL oferece ferramentas baseadas no GraphiQL, uma IDE para GraphQL.

Dentro do WordPress, o desenvolvedor consegue explorar o schema, escrever operações, receber autocomplete e executar queries e mutations.

Por exemplo, podemos escrever:

query {
  posts {
    nodes {
      title
    }
  }
}

e visualizar imediatamente a resposta.

Isso torna o próprio schema uma importante fonte de documentação durante o desenvolvimento.

GraphQL não significa ausência de segurança contra queries caras

Como o cliente possui grande liberdade para escolher campos e percorrer relacionamentos, servidores GraphQL precisam considerar o custo das operações recebidas.

WPGraphQL possui mecanismos para limitar a profundidade das queries.

Nas instalações atuais, novas instalações vêm com limitação de profundidade habilitada e profundidade máxima padrão de 15, segundo a documentação do projeto.

O objetivo é impedir consultas excessivamente aninhadas antes que sejam executadas.

Esse tipo de proteção é particularmente importante quando o endpoint GraphQL está disponível publicamente.

Onde o WPGraphQL é especialmente útil?

WPGraphQL é frequentemente utilizado quando WordPress atua como headless CMS.

Nesse modelo:

WordPress
    ↓
WPGraphQL
    ↓
Frontend

O WordPress pode continuar responsável por:

  • edição de conteúdo;
  • usuários;
  • taxonomias;
  • mídias;
  • permissões;
  • plugins;
  • regras de negócio.

Enquanto outra aplicação fica responsável pela interface.

Essa aplicação pode ser desenvolvida em:

  • React;
  • Next.js;
  • Astro;
  • SvelteKit;
  • aplicativos móveis;
  • ou qualquer tecnologia capaz de consumir uma API GraphQL.

WPGraphQL não exige uma tecnologia específica no cliente: qualquer sistema capaz de fazer as requisições necessárias pode consumir a API.

WPGraphQL substitui a REST API?

Não necessariamente.

Instalar WPGraphQL não remove nem desativa a REST API do WordPress.

As duas APIs podem existir no mesmo projeto.

Inclusive, uma mesma aplicação pode utilizar GraphQL para determinadas operações e REST para outras.

Elas representam modelos diferentes de interação com os dados.

A REST API do WordPress é orientada principalmente a recursos e endpoints.

GraphQL é orientado a um schema de tipos, campos e relacionamentos que o cliente pode consultar declarativamente.

A escolha entre eles depende das necessidades da aplicação, da complexidade das relações entre dados, do ecossistema de plugins, da estratégia de cache e da arquitetura do projeto.

Em resumo

GraphQL é uma especificação e linguagem de consulta para APIs baseada em um schema fortemente tipado.

Esse schema descreve tipos, campos, argumentos e relacionamentos, permitindo que aplicações clientes declarem exatamente quais dados pretendem receber.

WPGraphQL é uma implementação dessa arquitetura para WordPress.

Ele adiciona ao WordPress um schema GraphQL extensível, um endpoint para executar queries e mutations e uma camada que integra essas operações aos dados, permissões e APIs existentes no WordPress.

Uma query como:

query {
  posts(first: 5) {
    nodes {
      title
      author {
        node {
          name
        }
      }
    }
  }
}

parece apenas uma forma diferente de buscar posts.

Mas o conceito por trás dela é mais amplo.

A aplicação não está solicitando simplesmente um endpoint que representa posts.

Ela está navegando por um grafo tipado de dados, começando pelos posts, passando pela relação com seus autores e escolhendo exatamente quais campos deseja receber.

É essa combinação entre schema, tipos, seleção de campos e relacionamentos que define GraphQL — e que o WPGraphQL transporta para dentro do ecossistema WordPress.

Fontes e referências