Guia detalhado na criação e busca de endpoints personalizados da API REST WP

Esta postagem mostrará como criar endpoints REST personalizados do WordPress e diferentes métodos para realizar solicitações a eles. Haverá exemplos em PHP, jQuery e Javascript vanilla.

Suponho que você já esteja familiarizado com o que é WP REST API, mas aqui está um breve resumo. A API REST do WordPress é uma interface JSON para enviar e receber dados do seu site WordPress. Você pode acessar os endpoints (caminhos/URLs específicos) tanto externa quanto internamente. O WordPress já tem vários endpoints disponíveis, por exemplo, para buscar posts, categorias, pesquisar no site e muito mais. Veja uma visão geral dos endpoints padrão do WordPress aqui. Mas os desenvolvedores são totalmente livres para criar seus próprios endpoints personalizados usando esta API, seja para realizar ações ou buscar dados.

Começaremos com o primeiro passo; que está criando endpoints personalizados. Se você está interessado apenas em como fazer solicitações, pule para a segunda parte.

Criar endpoints personalizados

O registro de endpoints personalizados é feito em PHP. Você pode adicionar o código ao arquivo de código do seu tema functions.phpou de um plugin ativo. Faça uma função vinculada rest_api_inite use a função [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()para cada endpoint que você gostaria de adicionar.

Como primeiro parâmetro, register_rest_route()você precisa fornecer um namespace exclusivo para garantir que seus endpoints não entrem em conflito com nenhum outro. Use o slug do seu tema ou plugin. É uma prática comum incluir um /seguido de um número de versão para seu código. Como exemplo, usarei o namespace awhitepixel/v1. O segundo parâmetro é o caminho (que segue o namespace). Finalmente, você pode opcionalmente fornecer uma matriz como terceiro parâmetro com opções. Nesta matriz você pode, por exemplo, definir o método de solicitação (GET, POST ou qualquer outro), definir parâmetros e, mais importante, definir a função a ser executada quando esse endpoint for solicitado.

No mínimo, você deve fornecer os argumentos ‘método’ e ‘retorno de chamada’ (que é a função para lidar com os dados do terminal) como terceiro parâmetro. Para ‘método’ você pode defini-los como ‘ GET', 'POST', 'PUT', ou qualquer outro método de solicitação válido (ou uma matriz de vários), mas eu recomendo usar os padrões do WordPress para isso. Eles são os seguintes:

• WP_REST_Server::READABLE método ‘ GET‘
• WP_REST_Server::EDITABLE métodos ‘ POST‘, ‘ PUT‘ e ‘ PATCH‘
• WP_REST_Server::DELETABLE método ‘ DELETE‘
• WP_REST_Server::ALLMETHODS todos os métodos acima

Vamos criar um endpoint personalizado básico que pode ser alcançado usando solicitações GET:

Na linha #2, definimos nosso endpoint personalizado como ‘ awhitepixel/v1/getsomedata‘. O URL completo seria o URL raiz da API REST do WordPress prefixado, que é <yourdomain>/wp-json. Portanto, a URL completa para o endpoint acima seria ‘ <yourdomain>/wp-json/awhitepixel/v1/getsomedata‘. Na linha #4, fornecemos um nome de função como retorno de chamada, que adicionaremos em breve.

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

Ainda não definimos a função callback – que é a função para o código que trata da reação de usar esse endpoint. Ele deve retornar uma resposta válida REST (em JSON), portanto, você precisará retornar algo, mesmo que o endpoint não deva retornar dados. Você pode usar a função [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()function ou criar uma instância de WP_REST_Responseobjeto como retorno do callback. Como parâmetro para a função de retorno de chamada, obtemos um WP_REST_Requestobjeto que contém todas as informações sobre a solicitação – incluindo quaisquer parâmetros. Vamos criar uma função de callback simples que simplesmente envia algum texto como resposta:

function awhitepixel_rest_route_getsomedata( $request) {
    $response = 'Hello there!';
    return rest_ensure_response( $response );
}

Esta é a maneira mais básica de escrever um retorno de chamada. A função rest_ensure_response()garante que todos os dados que fornecemos (a string) sejam convertidos em uma resposta válida REST. Obviamente você vai querer adicionar mais código aqui, para fazer algo no WordPress ou buscar e enviar dados de volta.

Com o código acima (registrando o endpoint e a função de retorno de chamada), você pode tentar acessar a URL em seu navegador e ver o que obtém. (Lembre-se de liberar seus permalinks). Acessar <domain>/wp-json/awhitepixel/v1/getsomedatano navegador mostrará a string “Hello there!".

Aceitando parâmetros

É muito comum e útil permitir que os endpoints aceitem parâmetros. Por exemplo, se o seu site tiver, por exemplo, dados do produto, você desejará um endpoint no qual possa fornecer um ID do produto para obter os dados desse produto. Há duas maneiras de fazer isso. A maneira mais comum é usar a string de consulta GET (que são anexadas após a URL após um ?, separadas por &no formato key=value. Por exemplo, ‘ <endpoint>/product/?product_id=14‘). Alternativamente, você pode definir um padrão de URL “mais bonito”, onde os parâmetros fazem parte do caminho. Por exemplo ‘ <endpoint>/product/14/‘. Este último método requer algum conhecimento de regexes. Qual método você vai escolher depende de você, vou demonstrar os dois abaixo.

Parâmetros GET

Definir possíveis parâmetros GET para seu endpoint é usar a argschave ‘ ‘ no register_rest_route()terceiro parâmetro de. Para cada parâmetro que você deseja permitir, defina o valor da chave (no exemplo acima ‘ product_id‘) e uma matriz de opções para esse parâmetro. Como opções, você pode definir o formato do parâmetro (se espera, por exemplo, um número ou uma string) e também decidir se esse parâmetro é obrigatório ou não.

Como exemplo, queremos permitir que nosso endpoint aceite ‘ product_id‘ como um número não obrigatório.

Se você definir um parâmetro como true em required, o WordPress lidará com a devolução de uma resposta de erro 400. Da mesma forma se você passar um formato inválido, por exemplo “hello” como valor para um parâmetro que espera um número.

Na linha #15da função de retorno de chamada, você vê como obter o valor do parâmetro da solicitação; usando o método no objeto get_param()passado. WP_REST_RequestA título de exemplo, mostrarei diferentes respostas dependendo se product_idforam fornecidas ou não (lembre-se que definimos como opcional). A lógica de modificar seu código de acordo com os parâmetros fornecidos fica totalmente a seu critério e do seu projeto. Você pode ter menos endpoints que aceitem muitos parâmetros ou muito mais endpoints separados para cada caso específico.

Com o código acima, obterei "Olá!" quando visito <yourdomain>/awhitepixel/v1/getsomedatae "Retornar dados do produto para ID 14" quando vou para <yourdomain>/awhitepixel/v1/getsomedata/?product_id=14.

Parâmetros como parte do caminho

Se você quiser permitir que os parâmetros façam parte do caminho em vez de GET string de consulta, você pode fazer isso. Você então fornecerá um padrão regex no caminho – o segundo parâmetro para register_rest_route().

A criação de padrões regex pode parecer bastante enigmática, mas como é um tópico inteiro, você encontrará facilmente exemplos para casos específicos se pesquisar no Google. Mostrarei um exemplo de definição de uma regex que aceita um número de qualquer tamanho;

Como você pode ver na linha #2, adicionei o padrão regex (?P<product_id>[d]+)no final. Esses padrões significam que devemos coletar um número (d) de qualquer comprimento (+) e atribuir o valor coletado à chave de parâmetro product_id. E em nossa função de retorno de chamada, usamos exatamente o mesmo método que usamos ao configurar os parâmetros GET; get_param()no WP_REST_Requestobjeto fornecido para a função.

Com o código acima (após liberar os permalinks), podemos visitar a URL <yourdomain>/wp-json/awhitepixel/v1/getsomedata/14para obter nossa resposta. Esse método certamente resulta em URLs “mais bonitas”, mas o código pode facilmente ficar mais difícil de ler e corrigir bugs. Qualquer método que você escolher é com você.

Retornando a resposta adequada

Anteriormente, mencionei brevemente como a função de retorno de chamada precisa retornar uma resposta REST adequada. Até agora, usamos o mais simples rest_ensure_response(). Mas às vezes você pode querer mais controle do retorno do seu endpoint. Você pode, por exemplo, querer controlar o código de status de resposta HTTP. Digamos que você esteja criando um endpoint no qual pode fornecer uma ID de produto e obter dados para esse produto. Mas se esse ID do produto não existir ou qualquer outro parâmetro causar confusão, talvez você queira retornar um código de status de, por exemplo, 400 (solicitação inválida) ou 404 (não encontrado). Ou talvez 500 (erro do servidor). Sempre passar 200 (Sucesso) mesmo que a requisição tenha sido ruim pode causar problemas no final do remetente.

Eu recomendaria então sua função de retorno de chamada retornando um WP_REST_Responseobjeto. Com este objeto você pode controlar várias coisas, incluindo o código de status. É mais fácil do que você pensa! Na forma mais simples, você criaria uma nova instância de WP_REST_Response, forneceria uma matriz dos dados a serem retornados como primeiro parâmetro e o código de status como segundo parâmetro. Como um exemplo:

No exemplo acima armazenamos o retorno da awhitepixel_get_product()função em uma variável. Esta função não existe, e você deve substituí-la pela função que deve buscar (ou fazer) as ações que você deseja em seu projeto. Mas digamos que a função retorne uma matriz vazia e isso significa que algo deu errado (por exemplo, o produto não existia). Poderíamos então retornar um WP_REST_Responseobjeto com código de status 400 e, opcionalmente, uma mensagem como dados explicando por que ele falhou (linha #5-9). Caso contrário, retornamos os dados com o código de status 200 Success (linha #10).

Enviando solicitações para endpoints (personalizados)

Vamos para o outro lado, a parte de envio: como enviar solicitações para nossos endpoints personalizados. Normalmente você enviaria solicitações WP REST API usando Javascript e aqui você encontrará exemplos de uso de jQuery, biblioteca WordPress e Javascript vanilla. É incomum, mas possível, executar uma solicitação REST com PHP também – então incluí um exemplo disso também.

A primeira coisa a saber é que você obviamente precisa saber o URL completo para enviar uma solicitação. Eu não recomendo codificar o domínio (antes do endpoint), pois existem várias maneiras de obter isso se o seu Javascript estiver operando no WordPress. Em versões mais antigas do WordPress, você precisaria usar [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)()em PHP e passar a URL REST principal como uma variável Javascript global. Mas os exemplos abaixo mostram uma maneira mais nova e melhor de obter a URL raiz REST do site WordPress.

Outra coisa a ser observada é que, para o seu projeto, você provavelmente envolveria as solicitações como resultado de alguma ação. Para manter as coisas simples, estou preparando todas as solicitações no DOM, então você deve certificar-se de incluir o código da solicitação, por exemplo, como resultado de um visitante clicar em um botão.

Usando jQuery

Se você possui e deseja usar a biblioteca jQuery, pode usar sua [$.ajax](https://api.jquery.com/jquery.ajax/)()função.

Mas primeiro uma nota sobre as dependências do seu arquivo Javascript. Obviamente, seu script precisaria 'jquery'como dependência no enfileiramento. Mas para acessar facilmente a URL raiz REST do seu WordPress, adicione outra dependência; ‘wp-api-request’. Isso garante que a variável Javascript wpApiSettings.rootesteja disponível e contenha a URL raiz da API REST. Aqui está um exemplo de como você enfileiraria seu script para ilustrar essa dependência;

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'awp-javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'jquery', 'wp-api-request' ], 
        null, 
        true
    );
} );

A linha #5é a mais interessante; onde definimos tanto jQuery quanto wp-api-requestcomo dependência. Então, em nosso arquivo Javascript, podemos executar uma solicitação WP REST API da seguinte forma:

( function( $) {
    // Send request
    $.ajax( {
        url: wpApiSettings.root + 'awhitepixel/v1/getsomedata',
        method: 'GET',
        data: {
            product_id: 14
        },
        success: function( data) {
            console.log( data );
        }
    } );
} )( jQuery );

Isso é o mais básico possível. Usamos $.ajax()para enviar uma solicitação GET para a url definida. Como URL, usamos wpApiSettings.rootpara obter a URL raiz da API REST e, em seguida, anexamos o endpoint desejado após ela; no nosso caso, o endpoint personalizado que criamos anteriormente. Opcionalmente podemos passar parâmetros em ‘data’. O exemplo acima passa product_idcom o valor 14 para o endpoint. Finalmente, na successfunção, recebemos a solicitação (bem-sucedida) como parâmetro e estamos livres para fazer o que quisermos com ela. No exemplo acima, nós o imprimimos no console.

Usando a biblioteca do WordPress (não-jQuery)

Se o seu site WordPress não possui ou pode usar a biblioteca jQuery, você pode usar a biblioteca Javascript do WordPress para executar facilmente uma solicitação da API REST. A função é que está disponível no namespace apiFetchglobal do WordPress. é um método wrapper para a função padrão do navegador (que é demonstrado a seguir).wp``wp.apiFetch()``fetch()

Nosso Javascript precisará da dependência ‘wp-api’ para usar wp.apiFetch(). Por exemplo, poderíamos enfileirar o script assim:

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'wp-api' ], 
        null, 
        true
    );
} );

Você encontrará a dependência crítica em line #5. Com isso, garantimos que nosso arquivo Javascript esteja wp.apiFetch()disponível. Aqui está um exemplo básico de como usá-lo:

Tenha em mente que as linhas #9-13são apenas lógicas para executar a função depois que o DOM estiver pronto.

Um benefício de usar wp.apiFetch()sobre o normal fetch()é que podemos usar ‘path’ que requer apenas o endpoint, em vez de ‘url’ que requer a URL completa. Outro benefício é que a primeira “cadeia” de .then()retorna os dados já formatados em JSON. Quando você usa o original .fetch()você precisa de mais cadeias “.then()”. Dê uma olhada no próximo exemplo (“Using vanilla Javascript”) para ver o que quero dizer.

Tenha em mente que fetch()(e como consequência wp.apiFetch()) não fornece uma maneira “limpa” de passar parâmetros. Precisaremos construir manualmente a string de consulta GET em ‘path’, como fiz acima: '../getsomedata?product_id=14'.

Se você estiver interessado em como incorporar wp.apiFetche personalizar endpoints em um bloco Gutenberg, escrevi um tutorial separado sobre isso:

Usando Javascript de baunilha

Como um exemplo final de métodos Javascript para enviar solicitação para WP REST API, existe uma maneira baunilha pura, não WordPress, usando fetch(). Observe que eu uso a variável global do WordPress para obter a URL raiz REST. Se você estiver adicionando este script fora do WordPress, provavelmente precisará codificar o URL completo.

Como ainda quero acessar a variável global para a URL raiz WP REST, adiciono 'wp-api-request'dependência à minha função de enfileiramento Javascript, assim:

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'awp-javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'wp-api-request' ], 
        null, 
        true
    );
} );

E então em nosso arquivo Javascript um exemplo mais básico seria:

Como mencionado acima (“Usando a biblioteca do WordPress”) .fetch()não suporta uma maneira agradável e limpa de fornecer parâmetros. Portanto, você precisará criar manualmente a string de consulta (“?product_id=14”) no URL.

Tenha em mente que a solicitação de busca não retorna diretamente com os dados – ela retorna uma promessa. É por isso que precisamos encadear ” .then()” antes de podermos manipular os dados. Se isso soa estranho para você, recomendo procurar como trabalhar fetch()– há muitas explicações e exemplos no google que podem explicar melhor do que eu.

Se você quiser verificar o código de status da resposta REST para sua solicitação, faça assim;

No exemplo acima ao registrar endpoints personalizados, mencionei como você pode retornar diferentes códigos de status HTTP. O código acima mostra um exemplo de como verificar o código de status da resposta, que está disponível na propriedade do objeto retornado .status. No exemplo acima eu verifico se o código de status é diferente de 200 (Sucesso) na linha #5. Somente se o código de status for 200 eu converto o retorno de dados da promessa em JSON (linha #9).

Usando PHP

É menos comum, mas ainda possível, realizar requisições REST internamente no WordPress usando PHP. Aqui está como.

Para enviar uma solicitação WP REST API em PHP, criamos um WP_REST_Requestobjeto (exatamente como o que é passado para nossa função de retorno de chamada anteriormente neste post). Nesta instância do objeto, definimos o método (por exemplo, GET) e o caminho do endpoint. Opcionalmente, também podemos adicionar parâmetros. Em seguida, usamos a função do WordPress [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/)()com esta instância de solicitação. Finalmente, obtemos a resposta com a [response_to_data](https://developer.wordpress.org/reference/classes/wp_rest_server/response_to_data/)()função disponível na WP_REST_Server'classe s.

A chamada de função set_query_params()(line #3-5) é opcional e necessária apenas se você deseja passar parâmetros. Seguindo o fio vermelho neste post, incluirei um exemplo de passagem do parâmetro da função para o parâmetro REST key product_id.

A linha #6é para onde enviamos a solicitação. E na linha #7retornamos os dados da resposta. Então, se fôssemos chamar essa função PHP, por exemplo awp_do_php_rest_request( 14 ), obteríamos a resposta que definimos nesse endpoint (um array com uma string se você ainda usar o mesmo exemplo do início deste post).