Uma cobrança pode existir e, mesmo assim, uma consulta procurar o identificador errado. Ler as partes da URL, o endereço completo da operação, ajuda a separar o endereço do serviço dos valores usados para localizar os dados.
As partes do endereço
A URL https://api.example.com/v1/pagamentos/PAG-0001 tem três partes:
https: o esquema, que indica o HTTP protegido pelo TLS;api.example.com: o host, o nome do serviço de destino;/v1/pagamentos/PAG-0001: o caminho, que, nesse contrato, traz a versão, a coleção de cobranças e o número da cobrança.
Uma porta pode aparecer depois do host, separada por dois-pontos. Sem a porta, o HTTPS usa a porta padrão, a 443.
Um parâmetro de caminho é um trecho variável do caminho, como o número da cobrança em /v1/pagamentos/{id}. A URL não informa, sozinha, se esse trecho espera o número da cobrança, o número do pedido ou outro valor. Essa informação vem do contrato.
Os parâmetros de consulta
A URL https://api.example.com/v1/pagamentos?pedido_id=PED-0001 usa uma query string, a parte que vem depois do ponto de interrogação. No exemplo, a query string pesquisa as cobranças de um pedido. Vários parâmetros são separados pelo sinal &, como em ?pedido_id=PED-0001&pagina=2.
A query string também controla a paginação, a ordenação e outras opções, e não serve apenas para filtros. Os espaços e os caracteres especiais precisam ser codificados, porque a URL aceita só um conjunto limitado de caracteres. O espaço, por exemplo, pode aparecer como %20.
Uma senha ou um token na URL fica exposto, porque os endereços costumam ser gravados nos logs dos programas e dos servidores. Por isso, as credenciais costumam ir nos cabeçalhos, quando o contrato permite.
O valor certo na consulta errada
No gateway de pagamento, a consulta GET /v1/pagamentos/PED-0001, com o método GET, usado nas consultas, procura uma cobrança cujo número é PED-0001. A busca pelo pedido é GET /v1/pagamentos?pedido_id=PED-0001. Como não existe cobrança com o número PED-0001, a primeira consulta recebe o código 404, de recurso não encontrado.
O código 404 não prova que o pedido ficou sem pagamento. O código mostra o resultado daquela consulta, que procurou o identificador no lugar errado. Outras APIs organizam os endereços de outra forma, e o contrato de cada uma indica o lugar de cada identificador.
No suporte
Antes de concluir que um registro não existe, convém conferir qual identificador o endereço espera. O método e a URL registrados no log são comparados com a documentação, incluindo a versão, os parâmetros e o ambiente.
Para guardar
- O host identifica o serviço, e o caminho e a query string identificam a operação e os dados.
- O contrato define o significado de cada parâmetro.
- Os caracteres especiais da URL precisam de codificação.
- Uma credencial na URL fica exposta nos logs.
- Um identificador no lugar errado pode receber o código 404 sem provar a ausência do registro.
O pedido PED-0001 existe, mas a consulta GET /v1/pagamentos/PED-0001 recebe o código 404. O que conferir?
Se o caminho espera o número da cobrança ou o número do pedido. No contrato do gateway de pagamento, o pedido é pesquisado pela query string, e a consulta anterior procurou uma cobrança com esse número.
Toda API indica a versão no caminho, como em /v1?
Não. Algumas APIs usam o caminho, e outras usam um cabeçalho ou outra convenção. A forma de indicar a versão está na documentação de cada serviço.