Criar e buscar endpoints REST personalizados em blocos Gutenberg

Neste post, tentarei criar uma visão geral de como criar endpoints personalizados da API REST e realizar solicitações para eles em um bloco Gutenberg personalizado. Ou seja, fazer solicitações com fetchmétodos de informações não disponíveis nos armazenamentos de dados cadastrados do WordPress.

Um lembrete amigável: as informações mais básicas já estão disponíveis nos armazenamentos de dados do WordPress. Por exemplo, consultas básicas de postagens, páginas, tipos de postagem personalizados, taxonomias, autores, mídia e muito mais estão disponíveis sem a necessidade de criar seus próprios endpoints personalizados. Para acessar essas lojas, você prefere usar o módulo de dados principal do WordPress (withSelecte select()). Abaixo está uma parte do tutorial que se aprofunda em como fazer isso.

API REST do WordPress

Se você ainda não sabia; A API REST do WordPress é uma interface JSON para enviar e receber dados do seu site WordPress. Pode ser usado externamente ou internamente. Com o editor Gutenberg e a mudança para Javascript, os usos da API REST definitivamente aumentaram. A API REST do WordPress tem vários endpoints que podemos usar. Veja uma referência completa sobre todos os endpoints da API REST aqui. Você encontrará, por exemplo, endpoints para postagens e a maioria dos outros conteúdos internos – tanto para leitura quanto para atualização. Desenvolvedores de temas ou plugins podem registrar seus próprios endpoints personalizados.

Seu site WordPress tem um URL de API REST raiz, como padrão localizado em <your domain>/wp-json. Por exemplo, um WordPress local com a URL http://localhost/wordpress/pode acessar a API REST em http://localhost/wordpress/wp-json. A partir daí, precisamos anexar endpoints. Referindo-se à referência de endpoints acima, podemos recuperar uma lista de postagens mais recentes no endpoint /wp/v2/posts. Isso significa que, se você acessar http://localhost/wordpress/wp-json/wp/v2/postsem seu navegador, receberá uma resposta formatada em JSON das últimas postagens em seu site WordPress.

Uma nota sobre namespaces está em ordem. Um URL da API REST começa com um namespace (‘ wp/v2‘ é o namespace do WordPress’ como visto nos URLs de exemplo acima). Namespaces é um conceito para evitar conflitos no núcleo do WordPress, temas e plugins adicionando endpoints com o mesmo nome. Crie seu próprio namespace exclusivo – normalmente uma forma de slug do seu tema ou nome do plugin. Após o slug, uma regra geral é adicionar o número da versão, normalmente começando na v1. Como exemplo, o slug do meu tema é ‘ awhitepixel‘, então se eu fosse criar endpoints personalizados no meu tema eu usaria o namespace ‘ awhitepixel/v1‘. Com este namespace eu poderia registrar um endpoint ‘ posts‘ e não causaria problemas mesmo sendo idêntico ao nome do endpoint do WordPress.

Trabalhar com a API REST no WordPress é um tópico grande com muitas informações boas disponíveis. Neste post estou focando na usabilidade no editor Gutenberg e como recuperá-los em Javascript.

O que faremos e o que precisamos

A usabilidade para solicitar informações personalizadas tem uma ampla variedade de casos de uso, portanto, você geralmente precisa personalizar os exemplos de código abaixo para atender às suas necessidades. Os dados podem ser uma consulta de postagem personalizada, uma consulta SQL personalizada ou algo completamente diferente.

Quando criamos um endpoint personalizado, temos controle total sobre seu retorno. Podemos realizar qualquer tipo de operação e consulta no WordPress/PHP e passar isso como JSON. E no nosso bloco Gutenberg poderemos recuperar esse retorno e fazer o que quisermos com ele dentro da editfunção do bloco. Normalmente, você usaria os dados para apresentar ao usuário final uma opção ou informação no editor de blocos, mas também pode armazenar informações deles em seu bloco para uso posterior. Você também pode criar seus próprios armazenamentos personalizados para esses dados, mas não vou entrar em como fazer isso.

Suponho que você já esteja familiarizado com como criar blocos personalizados do Gutenberg, então não vou detalhar isso aqui.

Como criar um endpoint da API REST

O registro de um endpoint de API REST personalizado é feito em PHP. Você adicionaria esse código no seu tema functions.phpou em um código de plug-in ativo. Conecte uma função à ação rest_api_inite execute a função [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()para cada endpoint que você deseja registrar.

Forneça seu namespace como primeiro parâmetro, sua rota de endpoint como segundo e uma matriz de configurações como terceiro parâmetro para register_rest_route(). O quarto parâmetro controla se você deseja ou não substituir uma rota existente; não é algo que veremos aqui. No array para o terceiro parâmetro você deve no mínimo definir a propriedade ‘ callback‘ para uma função que seja responsável por retornar os dados do endpoint. Definir ‘ method‘ também é comum, por exemplo, definir seu ponto de extremidade como ‘ GET‘, ‘ POST‘, ‘ PUT‘, etc.

Vamos começar registrando um endpoint simples;

O namespace do meu tema é ‘ awhitepixel/v1‘ e estou registrando um endpoint ‘ mydata‘ dentro deste namespace. Isso significa que posso acessar minha API REST personalizada em http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.

Ao registrar (ou alterar) as rotas da API REST, você precisará liberar seus permalinks para que funcione. Você pode fazer isso visitando Configurações > Permalinks e simplesmente clicando em Salvar.

O código acima ainda não funciona, pois não defini a função definida como callback: awhitepixel_rest_route_mydata. A função de retorno de chamada recebe um parâmetro; uma matriz de dados com informações e argumentos passados ​​da solicitação. Finalmente, você precisa considerar cuidadosamente o retorno da sua função de retorno de chamada.

Em primeiro lugar, você deve sempre retornar algo de seu retorno de chamada de endpoint. Qualquer retorno será automaticamente convertido em JSON pelo WordPress. Isso significa que você pode retornar praticamente qualquer forma de dados em sua função; uma string, null, uma matriz ou [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)instância. Você também pode optar por retornar um [WP_REST_Response](https://developer.wordpress.org/reference/classes/wp_rest_response/)objeto para ter mais controle sobre, por exemplo, código de status ou informações de cabeçalho. Eu recomendo envolver o retorno na função [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()para garantir que sua resposta seja uma resposta REST válida.

Vamos definir nossa função de retorno de chamada e retornar uma string simples como início;

function awhitepixel_rest_route_mydata($data) {
    $response = 'Hello there!';
    return rest_ensure_response($response);
}

Com o código acima (e permalinks liberados), agora posso ir para o URL http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.

A partir daqui, podemos adicionar qualquer tipo de código em nossa função de retorno de chamada para gerar os dados adequados para retornar. Você pode consultar o conteúdo do WordPress com, por exemplo [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/), fazer consultas no banco de dados ou solicitar dados externos. Esta parte é com você.

Agora, vamos para o lado oposto; como fazer os pedidos.

Fazendo solicitações de API REST em Javascript

A execução da solicitação REST geralmente é feita usando [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)Javascript. O WordPress fornece seu próprio wrapper fetchque simplifica as solicitações da API REST do WordPress; [wp.apiFetch](https://developer.wordpress.org/block-editor/packages/packages-api-fetch/). Isto é o que vou usar no meu bloco Gutenberg personalizado. Lembre-se de que uma fetchsolicitação retorna uma “promessa" – portanto, precisamos encadear a .then()para lidar com o retorno da solicitação real. O uso básico é algo assim;

apiFetchnos permite fornecer uma pathpropriedade em vez de construir o URL completo. Tudo o que precisamos fornecer é o namespace e o endpoint, e apiFetchanexaremos isso ao URL raiz da API REST do WordPress. Dentro da .then()função temos acesso aos dados que já estão convertidos para JSON. É aqui que você faria algo com os dados. Normalmente você armazenaria os dados retornados, por exemplo, no estado do componente.

Abaixo está um exemplo de editcomponente de um bloco Gutenberg personalizado. É baseado em classe para ser usado statepara armazenar os dados retornados da solicitação da API REST. Isso também nos permite executar a solicitação componentDidMount()quando ela é montada pela primeira vez (consulte a documentação do React sobre métodos de ciclo de vida ). Tudo isso fornece um exemplo simples para você entender o conceito básico; não como uma receita para fazer exatamente assim. Você pode considerar usar ganchos e componentes funcionais do React ou construir um componente de ordem superior.

O exemplo acima é um composto baseado em classe que é fornecido à editfunção do bloco em registerBlockType(). Ele configura um objeto de estado de uma matriz para armazenar os dados (isso depende dos dados que você retorna, obviamente) e um booleano de status para saber quando a solicitação assíncrona retornou. Uma vez que o componente é montado (renderizado pela primeira vez) ele executa a função para realizar a apiFetchrequisição. Definimos o caminho para o endpoint que registramos no PHP acima. O método é por padrão GET, então não precisamos especificar isso em apiFetch. E dentro .then()da função quando a requisição está pronta atualizamos o estado do componente com os dados retornados.

Obviamente, a função de renderização do seu bloco faria mais com os próprios dados retornados. Você pode querer fornecer os dados ao usuário de alguma forma apresentando uma lista para talvez escolher. Tudo depende de que tipo de dados são e para que você deseja usá-los.

Passando argumentos para o endpoint

Em alguns casos, precisamos passar alguns argumentos para o endpoint. Os usos comuns são passar um ID após o terminal; por exemplo http://localhost/wordpress/wp-json/wp/v2/posts/14, retornaria o ID de postagem 14.

Isso é bem simples e é feito adicionando um padrão de pesquisa regex ao endpoint ao registrá-lo. Requer algum conhecimento de regexes para construir padrões complexos, mas abaixo está um exemplo que corresponde a um número e atribui a ele o nome ‘id’. Nomear as correspondências nos dá meios de acessar a variável em nossa função de retorno de chamada. Deixe-me mostrar o que quero dizer.

Vamos registrar uma nova rota de endpoint. Usamos o mesmo endpoint que fizemos anteriormente (‘ awhitepixel/v1/mydata‘), mas para essa rota adicionamos uma correspondência de regex para um número no final.

O padrão regex (?P<id>[d]+)parece enigmático, mas ficará bem claro com algum entendimento básico de regex. A [d]+parte corresponde a qualquer número (0-9) 1 ou mais vezes. As partes (?P<id>e )são para corresponder a um grupo nomeado. O nome do grupo é neste caso id, mas você pode nomear seu(s) grupo(s) como quiser.

Você pode optar por direcionar esse endpoint para uma função de retorno de chamada separada, mas optei por usar a mesma função para lidar com solicitações /mydatae /mydata/<ID>solicitações. Isso significa que eu posso na minha função de callback fazer:

function awhitepixel_rest_route_mydata($data) {
    if ($data['id']) {
        $response = 'Create return for ID: '. $data['id'];
    } else {
        $response = 'Create general return (no ID provided)';
    }
    return rest_ensure_response($response);
}

Lembre-se de que o parâmetro para a função de retorno de chamada contém os argumentos retornados. Como nomeei meu grupo correspondente como ‘ id‘, o valor correspondente estará acessível em $data['id']. E, finalmente, como uso a mesma função para lidar com solicitações com e sem ID, posso alternar facilmente entre os dois retornos diferentes.

Com isso (e links permanentes atualizados), obterei essas respostas para meus endpoints personalizados: