Fazendo o GraphQL funcionar no WordPress

O WordPress sem cabeça parece estar em voga ultimamente, com muitos novos desenvolvimentos ocorrendo apenas nas últimas semanas. Uma das razões para a explosão de atividade é o lançamento da versão 1.0 do WPGraphQL, um servidor GraphQL para WordPress.

O WPGraphQL fornece uma API GraphQL: uma maneira de buscar dados e postar dados em um site WordPress. Ele nos permite dissociar a experiência de gerenciamento de nosso conteúdo, que é feito via WordPress, da renderização do site, para o qual podemos usar a biblioteca do framework de nossa escolha (React, Vue.js, Gatsby, Next.js ou qualquer outro).

Até recentemente, o WPGraphQL era o único servidor GraphQL para WordPress. Mas agora outro plugin está disponível: GraphQL API for WordPress, de minha autoria.

Esses dois plugins têm o mesmo propósito: fornecer uma API GraphQL para um site WordPress. Você pode estar se perguntando: Por que outro plugin quando já existe o WPGraphQL? Esses dois plugins fazem a mesma coisa? Ou são para situações diferentes?

Deixe-me dizer isso primeiro: o WPGraphQL funciona muito bem. Eu não construí meu plugin por causa de qualquer problema com ele.

Eu construí a API GraphQL para WordPress porque eu estava trabalhando em um mecanismo para recuperar dados com eficiência , o que era muito adequado para o GraphQL. Então, então eu disse para mim mesmo: “Por que não?”, e eu construí. (E também algumas outras razões.)

Os dois plugins têm arquiteturas diferentes, dando-lhes características diferentes, o que facilita a realização de tarefas específicas com um plugin ou outro.

Neste artigo, descreverei, do meu próprio ponto de vista, mas da forma mais objetiva possível, quando o WPGraphQL é o caminho a seguir e quando a API do GraphQL para WordPress é a melhor escolha.

Use WPGraphQL se: usando Gatsby

Se você estiver construindo um site usando o Gatsby, há apenas uma opção: WPGraphQL.

A razão é que apenas o WPGraphQL possui o plugin de origem Gatsby para WordPress. Além disso, o criador do WPGraphQL, Jason Bahl, foi empregado até recentemente pelo Gatsby, então podemos confiar plenamente que este plugin atenderá às necessidades do Gatsby.

Gatsby recebe todos os dados do site WordPress e, a partir de então, a lógica do aplicativo estará totalmente do lado de Gatsby, não do WordPress. Portanto, nenhuma adição ao WPGraphQL (como as possíveis adições das @stream ou @defer ) faria muita diferença.

O WPGraphQL já é tão bom quanto o Gatsby precisa.

Use o WPGraphQL se: usando um dos novos frameworks headless

Como mencionei, ultimamente tem havido uma enxurrada de atividades no espaço headless do WordPress em relação a vários novos frameworks e projetos iniciais, todos eles baseados em Next.js:

• Colby Fayock criou o Next.js WordPress Starter.
• WebDevStudios lançou seu próprio Next.js WordPress Starter.
• O WP Engine criou o Headless WordPress Framework, que capacita seu serviço para hospedar e implantar sites sem cabeça do WordPress.

Se você precisar usar qualquer um desses novos frameworks headless, precisará usar o WPGraphQL, porque todos foram construídos em cima deste plugin.

Isso é um pouco lamentável: eu realmente adoraria que a API GraphQL para WordPress pudesse alimentá-los também. Mas para que isso aconteça, esses frameworks precisariam operar com o GraphQL por meio de uma interface , para que pudéssemos trocar os servidores do GraphQL.

Estou um pouco esperançoso de que qualquer uma dessas estruturas colocará essa interface no lugar. Perguntei sobre isso no fórum de discussão do Headless WordPress Framework e me disseram que poderia ser considerado. Também perguntei no fórum de discussão Next.js WordPress Starter do WebDevStudios, mas, infelizmente, minha pergunta foi imediatamente excluída, sem resposta. (Não é encorajador, é?)

Então WPGraphQL é então, atualmente e no futuro previsível.

Use qualquer um (ou nenhum) se: usando Frontity

Frontity é um framework React para WordPress. Ele permite que você crie um aplicativo baseado em React que é gerenciado no back-end via WordPress. Até mesmo a criação de postagens de blog usando o editor do WordPress é suportada imediatamente.

Frontity gerencia o estado do aplicativo, sem vazar como os dados foram obtidos. Embora seja baseado em REST por padrão, você também pode alimentá-lo via GraphQL implementando o plug-in de origem correspondente.

É assim que o Frontity é inteligente: o plugin de origem é uma interface para se comunicar com o provedor de dados. Atualmente, o único plug-in de origem disponível é o da API REST do WordPress. Mas qualquer um pode implementar um plug-in de origem para WPGraphQL ou API GraphQL para WordPress. (Esta é a abordagem que desejo que as estruturas baseadas em Next.js sejam replicadas.)

Conclusão : Nem o WPGraphQL nem a API GraphQL oferecem qualquer vantagem sobre o outro para trabalhar com Frontity, e ambos exigem algum esforço inicial para conectá-los.

Use WPGraphQL se: Criando um site estático

Nas duas primeiras seções, a conclusão foi a mesma: Use WPGraphQL. Mas minha resposta a essa conclusão foi diferente: enquanto com Gatsby eu não me arrependia, com Next.js eu me senti compelido a fazer algo a respeito.

Por que é que?

A diferença é que, enquanto o Gatsby é puramente um gerador de sites estáticos, o Next.js pode alimentar sites estáticos e ao vivo.

Eu mencionei que o WPGraphQL já é bom o suficiente para o Gatsby. Esta declaração pode realmente ser ampliada: WPGraphQL já é bom o suficiente para qualquer gerador de site estático . Uma vez que o gerador de site estático obtém os dados do site WordPress, é praticamente resolvido com o WordPress.

Mesmo que a API GraphQL para WordPress ofereça recursos adicionais, provavelmente não fará diferença para o gerador de site estático.

Portanto, como o WPGraphQL já é bom o suficiente e mapeou completamente o esquema do GraphQL (que ainda é um trabalho em andamento para a API do GraphQL para WordPress), o WPGraphQL é a opção mais adequada, agora e no futuro próximo.

Use a API do GraphQL se: estiver usando o GraphQL em um site ao vivo (ou seja, não estático)

Agora, a situação acima muda se quisermos que o GraphQL busque dados de um site ao vivo, como ao alimentar um aplicativo móvel ou plotar dados em tempo real em um site (por exemplo, para exibir análises) ou combinar as abordagens estática e ao vivo no mesmo site.

Por exemplo, digamos que criamos um blog estático simples usando uma das estruturas Next.js e queremos permitir que os usuários adicionem comentários às postagens do blog. Como essa tarefa deve ser tratada?

Temos duas opções: estática e ao vivo (ou dinâmica). Se optarmos pelo estático, os comentários serão renderizados junto com o restante do site. Então, sempre que um comentário for adicionado, devemos acionar um webhook para regenerar e reimplantar o site.

Esta abordagem tem alguns inconvenientes. O processo de regeneração e reimplantação pode levar alguns minutos, durante os quais o novo comentário não estará disponível. Além disso, se o site receber muitos comentários por dia, a abordagem estática exigirá mais tempo de processamento do servidor, o que pode se tornar caro (algumas empresas de hospedagem cobram com base no tempo do servidor).

Nessa situação, faria sentido renderizar o site estaticamente sem comentários e, em seguida, recuperar os comentários de um site ativo e renderizá-los dinamicamente no cliente.

Para isso, o Next.js é recomendado em vez do Gatsby. Ele pode lidar melhor com as abordagens estáticas e ao vivo, incluindo o suporte a diferentes saídas para usuários com diferentes recursos.

De volta à discussão do GraphQL: Por que eu recomendo a API GraphQL para WordPress ao lidar com dados ao vivo? Eu faço porque o servidor GraphQL pode ter um impacto direto na aplicação, principalmente em termos de velocidade e segurança .

Para um site puramente estático, o site WordPress pode ser mantido privado (pode até estar no laptop do desenvolvedor), então é seguro. E o usuário não estará esperando por uma resposta do servidor, então a velocidade não é necessariamente de importância crítica.

Para um site ao vivo, porém, a API GraphQL será tornada pública, então a segurança dos dados se torna um problema. Devemos garantir que nenhum agente malicioso possa acessá-lo. Além disso, o usuário estará esperando por uma resposta, então a velocidade se torna uma consideração crítica.

A esse respeito, a API GraphQL para WordPress tem algumas vantagens em relação ao WPGraphQL .

O WPGraphQL implementa medidas de segurança, como desabilitar a introspecção por padrão. Mas a API GraphQL para WordPress vai além, desativando o endpoint único por padrão (juntamente com várias outras medidas). Isso é possível porque a API GraphQL para WordPress oferece consultas persistentes de forma nativa.

Quanto à velocidade, as consultas persistentes também tornam a API mais rápida, pois a resposta pode ser armazenada em cache via HTTP em várias camadas, incluindo o cliente, a rede de entrega de conteúdo e o servidor.

Esses motivos tornam a API GraphQL para WordPress mais adequada para lidar com sites ao vivo.

Use a API GraphQL se: Expor dados diferentes para usuários ou aplicativos diferentes

O WordPress é um sistema de gerenciamento de conteúdo versátil, capaz de gerenciar conteúdo para vários aplicativos e acessível a diferentes tipos de usuários.

Dependendo do contexto, podemos precisar de nossas APIs GraphQL para expor dados diferentes, como:

• expor determinados dados a usuários pagos, mas não a usuários não pagos,
• expor determinados dados ao aplicativo móvel, mas não ao site.

Para expor dados diferentes, precisamos fornecer versões diferentes do esquema GraphQL .

WPGraphQL nos permite modificar o esquema (por exemplo, podemos remover um campo registrado). Mas o processo não é simples: as modificações de esquema devem ser codificadas e não é fácil entender quem está acessando o quê e onde (por exemplo, todos os esquemas ainda estariam disponíveis em um único ponto de extremidade, /graphql ).

Por outro lado, a API GraphQL para WordPress suporta nativamente este caso de uso: oferece endpoints personalizados, que podem expor dados diferentes para contextos diferentes, como:

• /graphql/mobile-app e /graphql/website ,
• /graphql/pro-users e /graphql/regular-users .

Cada endpoint personalizado é configurado por meio de listas de controle de acesso, para fornecer acesso granular ao usuário campo por campo, bem como um modo de API pública e privada para determinar se os metadados do esquema estão disponíveis para todos ou apenas para usuários autorizados.

Esses recursos se integram diretamente ao editor do WordPress (ou seja, Gutenberg). Portanto, a criação dos diferentes esquemas é feita visualmente, semelhante à criação de uma postagem no blog. Isso significa que todos podem produzir esquemas GraphQL personalizados , não apenas desenvolvedores.

A API GraphQL para WordPress fornece, acredito, uma solução natural para este caso de uso.

Use a API GraphQL se: interagindo com serviços externos

O GraphQL não é apenas uma API para buscar e postar dados. Tão importante (embora muitas vezes negligenciado), também pode processar e alterar os dados – por exemplo, alimentando-os a algum serviço externo, como enviar texto para uma API de terceiros para corrigir erros gramaticais ou fazer upload de uma imagem para uma entrega de conteúdo rede.

Agora, qual é a melhor maneira de o GraphQL se comunicar com serviços externos? Na minha opinião, isso é melhor realizado por meio de diretivas, aplicadas ao criar ou recuperar os dados (não muito diferente de como os filtros do WordPress operam).

Eu não sei o quão bem o WPGraphQL interage com serviços externos, porque sua documentação não o menciona, e a base de código não oferece um exemplo de nenhuma diretiva ou documento de como criar um.

Em contraste, a API GraphQL para WordPress tem suporte robusto para diretivas . Cada diretiva em uma consulta é executada apenas uma vez no total (em oposição a uma vez por campo e/ou objeto). Esse recurso permite uma comunicação muito eficiente com APIs externas e integra a API GraphQL em uma nuvem de serviços.

Por exemplo, essa consulta demonstra uma chamada para a API do Google Translate por meio de uma diretiva @translate , para traduzir os títulos e trechos de muitas postagens do inglês para o espanhol. Todos os campos de todas as postagens são traduzidos juntos, em uma única chamada.

A API GraphQL para WordPress é uma escolha natural para este caso de uso.

Nota : Na verdade, o mecanismo no qual a API GraphQL para WordPress é baseada, GraphQL by PoP, foi projetado especificamente para fornecer recursos avançados de manipulação de dados. Essa é uma de suas características distintas. Para um exemplo extremo do que ele pode alcançar, confira o guia “Enviando um boletim informativo localizado, usuário por usuário”.

Use o WPGraphQL se: você quiser uma comunidade de suporte

Jason Bahl fez um excelente trabalho ao reunir uma comunidade em torno do WPGraphQL. Como resultado, se você precisar solucionar problemas de sua API GraphQL, provavelmente encontrará alguém que possa ajudá-lo.

No meu caso, ainda estou me esforçando para criar uma comunidade de usuários em torno da API GraphQL para WordPress, e certamente não chega nem perto do WPGraphQL.

Use a API GraphQL se: você gosta de inovação

Eu chamo a API GraphQL para WordPress de um servidor GraphQL “prospectivo”. A razão é que muitas vezes navego na lista de solicitações para a especificação GraphQL e implemento algumas delas com bastante antecedência (especialmente aquelas com as quais sinto alguma afinidade ou que posso suportar com pouco esforço).

A partir de hoje, a API GraphQL para WordPress suporta vários recursos inovadores (como execução de várias consultas e namespace de esquema), oferecidos como opt-in, e há planos para mais alguns.

Use o WPGraphQL se: você precisar de um esquema completo

O WPGraphQL mapeou completamente o modelo de dados do WordPress, incluindo:

• mensagens e páginas,
• tipos de postagem personalizados,
• categorias e tags,
• taxonomias personalizadas,
• meios de comunicação,
• cardápios,
• definições,
• Comercial,
• comentários,
• plug-ins,
• temas,
• widgets.

A API GraphQL para WordPress está mapeando progressivamente o modelo de dados a cada nova versão. A partir de hoje, a lista inclui:

• mensagens e páginas,
• tipos de postagem personalizados,
• categorias e tags,
• taxonomias personalizadas,
• meios de comunicação,
• cardápios,
• definições,
• Comercial,
• comentários.

Portanto, se você precisar buscar dados de um plug-in, tema ou widget, atualmente apenas o WPGraphQL faz o trabalho.

Use o WPGraphQL se: você precisar de extensões

O WPGraphQL oferece extensões para muitos plugins, incluindo Advanced Custom Fields, WooCommerce, Yoast, Gravity Forms.

A API GraphQL para WordPress oferece uma extensão para o Events Manager e continuará adicionando mais após o lançamento da versão 1.0 do plug-in.

Use um dos dois: Criando blocos para o editor do WordPress

Tanto o WPGraphQL quanto a API GraphQL para WordPress estão atualmente trabalhando na integração do GraphQL com o Gutenberg.

Jason Bahl descreveu três abordagens pelas quais essa integração pode ocorrer. No entanto, como todos eles têm problemas, ele está defendendo a introdução de um registro do lado do servidor no WordPress, para permitir a identificação dos diferentes blocos Gutenberg para o esquema GraphQL.

A API GraphQL para WordPress também possui uma abordagem de integração com o Gutenberg, baseada na estratégia “criar uma vez, publicar em qualquer lugar”. Ele extrai dados de bloco do conteúdo armazenado e usa um único tipo de Block para representar todos os blocos. Essa abordagem pode evitar a necessidade do registro do lado do servidor proposto.

A solução do WPGraphQL pode ser considerada provisória, pois dependerá da aceitação da comunidade do uso de um registro do lado do servidor, e não sabemos se ou quando isso acontecerá.

Para a API GraphQL para WordPress, a solução dependerá inteiramente de si mesma e, de fato, já é um trabalho em andamento.

Como ele tem uma chance maior de produzir uma solução funcional em breve, eu recomendaria a API GraphQL para WordPress . No entanto, vamos aguardar que a solução seja totalmente implementada (em algumas semanas, conforme o plano) para ter certeza de que funciona conforme o esperado, e então atualizarei minha recomendação.

Use a API GraphQL se: Distribuindo blocos por meio de um plug-in

Cheguei a uma conclusão: poucos plugins (se houver) parecem estar usando o GraphQL no WordPress.

Não me entenda mal: o WPGraphQL ultrapassou 10.000 instalações. Mas acredito que essas são principalmente instalações para alimentar o Gatsby (para executar o Gatsby) ou para o Next.js (para executar um dos frameworks headless).

Da mesma forma, o WPGraphQL tem muitas extensões, como descrevi anteriormente. Mas essas extensões são apenas isso: extensões. Eles não são plugins independentes.

Por exemplo, a extensão WPGraphQL para WooCommerce depende dos plugins WPGraphQL e WooCommerce. Se um deles não estiver instalado, a extensão não funcionará, e tudo bem. Mas o WooCommerce não tem a opção de confiar no WPGraphQL para funcionar; portanto, não haverá GraphQL no plugin WooCommerce.

Meu entendimento é que não há plugins que usem GraphQL para executar funcionalidades para o próprio WordPress ou, especificamente, para alimentar seus blocos Gutenberg.

A razão é simples: nem o WPGraphQL nem a API GraphQL para WordPress fazem parte do núcleo do WordPress. Assim, não é possível confiar no GraphQL da mesma forma que os plugins podem confiar na API REST do WordPress. Como resultado, os plugins que implementam blocos do Gutenberg só podem usar REST para buscar dados para seus blocos, não GraphQL.

Aparentemente, a solução é esperar que uma solução GraphQL (provavelmente WPGraphQL) seja adicionada ao núcleo do WordPress. Mas quem sabe quanto tempo isso vai levar? Seis meses? Um ano? Dois anos? Mais tempo?

Sabemos que o WPGraphQL está sendo considerado para o núcleo do WordPress porque Matt Mullenweg sugeriu isso. Mas muitas coisas devem acontecer antes disso: aumentar a versão mínima do PHP para 7.1 (exigida tanto pelo WPGraphQL quanto pela API GraphQL para WordPress), além de ter um desacoplamento, entendimento e roteiro claros para qual funcionalidade o GraphQL potencializará.

(A edição completa do site, atualmente em desenvolvimento, é baseada em REST. E quanto ao próximo recurso principal, blocos multilíngues, a ser abordado na fase 4 do Gutenberg? Se não for esse, qual será o recurso?)

Tendo explicado o problema, vamos considerar uma solução potencial — uma que não precisa esperar!

Alguns dias atrás, tive outra percepção: da base de código da API GraphQL para WordPress, posso produzir uma versão menor, contendo apenas o mecanismo GraphQL e nada mais (sem UI, sem endpoints personalizados, sem cache HTTP, sem controle de acesso, não nada). E esta versão pode ser distribuída como uma dependência do Composer, para que os plugins possam instalá-la para alimentar seus próprios blocos.

A chave para esta abordagem é que este componente deve ser de uso específico para o plugin, não deve ser compartilhado com mais ninguém. Caso contrário, dois plugins que fazem referência a este componente podem modificar o esquema de forma que eles se sobreponham.

Felizmente, recentemente resolvi definir o escopo da API GraphQL para WordPress. Então, eu sei que posso fazer o escopo completo, produzindo uma versão que não entrará em conflito com nenhum outro código no site.

Isso significa que funcionará para qualquer combinação de eventos :

• Se o plugin que contém o componente for o único a usá-lo;
• Se a API GraphQL para WordPress também estiver instalada no mesmo site;
• Se outro plugin que também incorpora este componente estiver instalado no site;
• Se dois plugins que incorporam o componente referem-se à mesma versão do componente ou a versões diferentes.

Em cada situação, o plug-in terá seu próprio mecanismo GraphQL privado e independente, no qual pode confiar totalmente para alimentar seus blocos Gutenberg (e não precisamos temer nenhum conflito).

Esse componente, a ser chamado de API GraphQL privada , deve ficar pronto em algumas semanas. (Já comecei a trabalhar nisso.)

Portanto, minha recomendação é que, se você quiser usar o GraphQL para alimentar os blocos do Gutenberg em seu plug-in, aguarde algumas semanas e, em seguida, confira a API GraphQL para o irmão mais novo do WordPress, a API GraphQL privada.

Conclusão

Mesmo que eu tenha uma pele no jogo, acho que consegui escrever um artigo que é principalmente objetivo.

Fui honesto ao afirmar por que e quando você precisa usar o WPGraphQL. Da mesma forma, fui honesto ao explicar por que a API GraphQL para WordPress parece ser melhor que o WPGraphQL para vários casos de uso.

Em linhas gerais, podemos resumir da seguinte forma:

• Fique estático com o WPGraphQL ou vá ao ar com a API GraphQL para WordPress.
• Jogue pelo seguro com o WPGraphQL ou invista (para um retorno potencialmente digno) na API GraphQL para WordPress.

Em uma nota final, eu gostaria que os frameworks Next.js fossem rearquitetados para seguir a mesma abordagem usada pela Frontity: onde eles podem acessar uma interface para buscar os dados de que precisam, em vez de usar uma implementação direta de alguma solução específica ( o atual é WPGraphQL). Se isso acontecesse, os desenvolvedores poderiam escolher qual servidor subjacente usar (seja WPGraphQL, GraphQL API para WordPress ou alguma outra solução introduzida no futuro), com base em suas necessidades - de projeto para projeto.

Links Úteis

• WPGraphQL: documentação, página de download, repositório de código
• API GraphQL para WordPress: documentação, página de download, repositório de código
• “Oficina de Integração WordPress Gatsby”
  Vídeo do YouTube com demonstração do WPGraphQL
• “Introdução à API GraphQL para WordPress”
  Vídeo do YouTube com demonstração da API GraphQL para WordPress