Casos de uso: HTTP status 204 ou 404 about minha-receita HOT 10 CLOSED

Acho que o erro nessa historia está em encarar o CNPJ como um recurso ou não. Se não se quer retornar 404, a URL de busca deveria ser encarado como um recurso (uma coleção) e a busca do CNPJ deveria estar na query string. Assim, um resultado vazio pode vir com um HTTP de sucesso. Porém, se o CNPJ tem um URL, então ele é um recurso que pode existir ou não, entendendo que 404 é quando não existe.

from minha-receita.

Falando de forma mais pragmática, já vi muito código em que apenas é verificado se o http status está na faixa 2xx (if >= 200 and < 300) antes de prosseguir. Não retornar um conteúdo nesse caso pode causar bugs inesperados para os usuários da API com menos experiência em códigos http

Além disso um ponto que me confunde nessa decisão é o ponto mencionado

A classe de status 2xx (Sucesso) indica que a requisição do cliente foi recebida, compreendida e aceita com sucesso.

Na minha interpretação essa descrição só faz sentido para uma chamada com side-effect, que entendo como o significo do “aceita com sucesso”. Eu não conheço bem a api, mas não entendo por que o endpoint é uma chamada POST ao invés de GET, já que ao me parecer superficialmente pela documentação é uma chamada onde eu espero uma resposta, e não que causo alguma alteração, e nesse caso a descrição do 204 não encaixaria

Se eu espero um retorno, e não recebo nada sem ter erro, me parece estranho. Por outro lado se eu não necessariamente eu espero um retorno, e a chamada também não tem efeito colateral, pra que eu fiz a chamada?

from minha-receita.

Falando de forma mais pragmática, já vi muito código em que apenas é verificado se o http status está na faixa 2xx (if >= 200 and < 300) antes de prosseguir. Não retornar um conteúdo nesse caso pode causar bugs inesperados para os usuários da API com menos experiência em códigos http

Além disso um ponto que me confunde nessa decisão é o ponto mencionado

A classe de status 2xx (Sucesso) indica que a requisição do cliente foi recebida, compreendida e aceita com sucesso.

Na minha interpretação essa descrição só faz sentido para uma chamada com side-effect, que entendo como o significo do “aceita com sucesso”. Eu não conheço bem a api, mas não entendo por que o endpoint é uma chamada POST ao invés de GET, já que ao me parecer superficialmente pela documentação é uma chamada onde eu espero uma resposta, e não que causo alguma alteração, e nesse caso a descrição do 204 não encaixaria

Se eu espero um retorno, e não recebo nada sem ter erro, me parece estranho. Por outro lado se eu não necessariamente eu espero um retorno, e a chamada também não tem efeito colateral, pra que eu fiz a chamada?

Bom, mas neste caso, o problema está do lado do tratamento das respostas recebidas da API e não na API em si, vale lembrar que o programador precisa se adaptar ao recurso ao qual ele está usando, e, arriscaria a dizer também, que precisa tomar cuidados especiais dependendo do recurso que está consumindo.
Eu, particularmente sempre procuro por um 200 no meu response, pois sei que é a única coisa que me retornará algo válido para mostrar ao usuário, todo o restante necessita de tratamento.

Conforme eu comentei no outro projeto, eu sempre fico na dúvida entre estes status codes, pois a especificação diz claramente que os status 4xx são erros provenientes do cliente.
Eu entendo a questão do CPF estar em um URL e isso, talvez justificar o 404, mas ainda assim não me convenço muito, pois ele está no URL como um parâmetro de caminho, assim como seria um parâmetro em um request com queryString.

Na discussão (do stackoverflow) que linkei na discussão original, a resposta mais completa aponta que talvez o melhor cenário seria o retorno de um status code 200 com o corpo vazio, em vez do 204, visto que 204, na opinião dele também não serviria, e o 404 seria somente quando há algum erro por parte do cliente.

Mas enfim, acho essa uma discussão muito boa, e gosto de ver todos os pontos de vista.

from minha-receita.

O Path da URL e query string já estarão encriptados.

Verdade! Pensei, fiz e falei besteira. Depois vou criar uma issue para mudar isso! Obrigado pela correção 💜

from minha-receita.

Enão entendo por que o endpoint é uma chamada POST ao invés de GET

Acho que isso não está documentado em nenhum lugar mesmo — falha minha. A ideia era priorizar a privacidade. Passando o CNPJ como parte do corpo da requisição HTTPS, ele fica encriptado e as camadas intermediárias (provedor, proxies, VPN) não precisam saber qual CNPJ você está consultando.

from minha-receita.

Alguns pontos interessantes que a discussão levantou no Twitter:

Sugestão: deixe claro na documentação que pode ser que um CNPJ exista mas não seja servido pela API, dado que essa base tem as empresas e não os entes públicos etc. Outro exemplo são os CNPJs de campanha (se não me engano a base da RFB tem alguns, mas não todos como no TSE).
@turicas em https://twitter.com/turicas/status/1357441742384037889

E respondi com:

Interessante. Concordo demais com isso. Mas ao concordar com isso, eu começo a achar que 204 não seja uma solução tão boa quanto pensei… pois cria mais necessidade de documentação explicação.

Coisa que o corpo de uma resposta 404 resolveria — inclusive com uma UX melhor, chuto.
https://twitter.com/cuducos/status/1357443263238729728

Acho que a única coisa que me faz estar em cima do muro ainda é o que a @larien coloca:

No caso do CNPJ, o cliente pode muito bem inserir CNPJ que não existe. Na minha visão, o cliente teria feito algo errado se tivesse inserido um CNPJ inválido (e nesse caso vai 400 ou outro). Se ele inseriu um CNPJ válido e ele não existe, o recurso não foi achado :P
https://twitter.com/larienmf/status/1357439703000244226

from minha-receita.

Sobre o CNPJ estar na URL (como mencionado pelo @cawal e pelo @RodriAndreotti) vale mencionar que a URL não contém o CNPJ. O CNPJ é passado como um parâmetro no corpo de uma requisição POST. Se isso muda alguma coisa? Não sei.

Mas o cliente está acessando uma URL que existe, e está passando parâmetros válidos no caso de um CNPJ válido porém inexistente.

(Comentário genérico, de contexto, sem chegar a lugar nenhum… desculpem! Hahaha…)

from minha-receita.

Mas veja, esta situação se encaixa também no 204, pois ele foi desenhado esperando um input (o CNPJ no post), porém, também existe a possibilidade de se retornar um status 200 com alguma mensagem de erro no corpo.

from minha-receita.

Enão entendo por que o endpoint é uma chamada POST ao invés de GET

Acho que isso não está documentado em nenhum lugar mesmo — falha minha. A ideia era priorizar a privacidade. Passando o CNPJ como parte do corpo da requisição HTTPS, ele fica encriptado e as camadas intermediárias (provedor, proxies, VPN) não precisam saber qual CNPJ você está consultando.

Mas se está usando HTTPS o socket entre cliente e serviço já é encriptado por TLS na camada de transporte. O Path da URL e query string já estarão encriptados.

O GET seria o método mais adequado mesmo.

from minha-receita.

Sobre o CNPJ estar na URL (como mencionado pelo @cawal e pelo @RodriAndreotti) vale mencionar que a URL não contém o CNPJ. O CNPJ é passado como um parâmetro no corpo de uma requisição POST. Se isso muda alguma coisa? Não sei.

Muda sim, =) pois o recurso/URL acessado (busca) existe. Então, não deve retornar 404 e sim uma representação de um resultado vazio. Nessa API eu só mudaria o POST, pois POST teria a semântica de CRIAR um novo recurso (ou um efeito colateral) no HTTP, sendo mais adequado o GET para uma busca sem outros efeitos. Para ambos não faz sentido retornar 404.

from minha-receita.