Hoje comecei a estudar sobre Web APIs do tipo REST, para fazer uma API bacana para as Funções ZZ. A ideia é facilitar o acesso às funções por outros programas, via Internet.
Como parte de meus estudos, fui ver como se comportam as Web APIs de serviços famosos, para ver nos exemplos “do mundo real” quais as melhores práticas de sua implementação.
Comecei por uma tarefa bem simples: o que o servidor responde quanto eu tento acessar uma URL inválida na API?
Eu esperava encontrar um padrão, e simplesmente usar este padrão na minha própria API. Mas veja só o que encontrei.
Dropbox
{
error: "Not Found"
}
Flickr
http://api.flickr.com/services/rest/?format=json&method=foo
jsonFlickrApi({
"stat":"fail",
"code":112,
"message":"Method \"foo\" not found"
})
http://ajax.googleapis.com/ajax/services/foo
404
http://ajax.googleapis.com/ajax/services/search/foo
404
https://www.googleapis.com/language/foo
"Not Found"
https://www.googleapis.com/language/translate/foo
"Not Found"
https://graph.facebook.com/foo
{
"error": {
"message": "(#803) Some of the aliases you requested do not exist: foo",
"type": "OAuthException",
"code": 803
}
}
A documentação me disse que eu encontraria esta mensagem de erro:
{
"errors": [
{
"message": "Sorry, that page does not exist",
"code": 34
}
]
}
Eu juro que tentei, mas essa mensagem específica eu não consegui ver :)
404
https://api.twitter.com/1/foo.json
404
https://api.twitter.com/1/statuses/foo.json
{
error: "Could not authenticate you.",
request: "/1/statuses/foo.json"
}
https://api.twitter.com/1/statuses/show.json?id=foo
{
request: "/1/statuses/show.json?id=foo",
error: "No status found with that ID."
}
Conclusão
Nenhuma :)
Ainda não sei qual é o “certo” a se fazer quando alguém tentar acessar uma URL inválida dentro da minha API.
bom também estou estudando WebService REST, acredito que o corpo do recurso não importe desde que vc coloque no cabeçalho HTTP o código 404, ai o cliente que vai consumir seu recurso decide o que fazer
Olá!
Acho que, se o que aconteceu é realmente um recurso não encontrado, 404 é mais que suficiente. Assim, você já aproveita a semântica do HTTP – afinal, 404 diz tudo que o você quer comunicar :)
Sobre boas APIs para comparar, este cara já fez o trabalho de garimpar :)
Código HTTP 404 geralmente é suficiente. Nem precisa de corpo na mensagem.
Com isso não tem como confundir com uma mensagem válida.
Nesses casos onde tem um monte de informação (ex: Facebook), o servidor está mandando um HTTP 200 com uma mensagem de verdade (soft 404)
Esse é um dos principais problemas que nós desenvolvedores enfrentamos..
Falta de padrão.. =//
Eu pessoalmente não gosto de fazer grandes distinções entre Web Services e páginas/aplicações web. Principalmente quando falamos de Web Services REST, que são baseados no protocolo HTTP e seus verbos, que são também utilizados em páginas/aplicações web (pelo menos o POST e o GET).
O protocolo HTTP já tem por padrão algumas respostas de erro, por exemplo o famoso 404, que para os desenvolvedores web é um simples “not found”.
Projeto APIs REST e sou a favor que elas sejam mnemônicas, mas também acho que não vale a pena reinventar a roda em certos casos. Considero a resposta 404 bastante aceitável como retorno para um recurso não existente. A única ressalva que faço é que sua API deve respeitar o formato solicitado e retornar algo válido, um json, xml, texto puro, etc válido, para não forçar o desenvolvedor a fazer ajustes ou gambiarras no código para respostas diferentes do que ele esperava. Por exemplo:
json:
{
error: “404″
}
ou simplesmente:
{
“404″
}
xml:
404
ou
404
plain text:
404
Mas infelizmente ainda não existe nada que normatize isso e defina um padrão, principalmente quando falamos de ws REST.
As mensagens de erro de um API podem ajudar muito o desenvolvedor, e em alguns casos elas precisam ser bem claras, como por exemplo: “o recurso existe mas o usuário excedeu o limite de requisições.” O desenvolvedor precisa saber disso pra detectar que o erro não é, a princípio, em seu código.
Minha sugestão é ser coerente. Adote um único padrão para suas mensagens de erro. O twitter peca nisso um bocado.
Se a url é inválida então acho que deveria retornar 404, se ela é válida, mas tem algo errado com os parâmetros então retorna uma resposta no formato requerido (json, xml) com a descrição do erro. Eu esperaria isto de uma api de rest…
Massa ter uma API para as ZZs!
Véi, passei por isso outro dia… por aqui, assumimos que REST é encapsulado pelo HTTP, então o *certo* seria retornar o HTTP header como 404. E só.
Assumimos tb que REST deixa vc definir como a comunicação vai fluir, então não há “padrão de retorno” a menos que vc o defina. Por aqui deixamos a página padrão de 404 do servidor.
[]s
Em termos de REST o correto é responder com status code 404.
O corpo da resposta com erro só é útil se o cliente não quiser tratar o HTTP, mas daí já se perde o sentido em ser REST.
Pois é, no meu caso com as Funções, onde o que mais importa é mesmo o texto de retorno, me encaixei no “perde o sentido em ser REST”. Já desisti de querer me encaixar nestas quatro letrinhas :)
Que tal redirecionar para uma página de busca.
Ou informar que a informação que busca não está na página que foi acessada e ter a busca junto. (tipo wordpress).
Paulo, na API não tem navegação, acho que você está confundindo com um 404 de um website normal.
uma resposta 404 não requer um conteúdo no corpo da resposta.
com a url correta e os params errados, não é o caso de retornar um 404. acho que o que mais se encaixa nesse caso é um 422 com a descrição do erro no corpo, no formato solicitado.
redirecionar para uma página de busca não é nem um pouco recomendado numa API Rest.
O que vc pode fazer eu nao sei, mas algo assim nao seria ruim:
https://github.com/foo/bar ;)
Oi Aurélio, conforme alguns amigos responderam, para um uso mais semântico do http o correto seria retornar error code 404. Quanto à mensagem deste não há restrições na própria rfc fala que esta pode ser alterada.
Recomento o REST in Pratice do Jim Webber, um dos gurus de arquitetura rest.
abraços
Isso caso o client esteja solicitando dados como application/json, xml, atom ou etc. Porém se o accept content-type da request for algo como text/html, é legal retornar uma página agradável de erro.
Olá Aurélio,
Eu uso a mesma abordagem da API do Flickr e do Facebook (que você postou o código acima). Gero um mapa de constantes numéricas para erros e retorno uma breve mensagem de erro em outro campo.
Não retorno 404 porque não acho que seja o mais claro para o usuário.
Abraço.
Obrigado a todos pelos comentários! Decidi retornar o 404 *e* uma mensagem breve de erro (igual a do Dropbox), para satisfazer as duas pontas.
E estudando melhor também percebi que REST não é o meu objetivo. Gostei do conceito e poderei usá-lo no futuro, mas hoje, pras ZZ, é muito além do que eu preciso.
Coloquei online uma versão inicial da API em http://api.funcoeszz.net/0/. Sugestões são bem-vindas!
Primeiro você deve executar um coneg (Content Negotiation, http://gewis.win.tue.nl/~koen/conneg/), nele você determina se você suporta ou não o content-type solicitado, caso não suporte, retornar um 406.
Se suportar, devolve um 404, com o corpo no formato suportado pelo usuário. Isso vai se adequar ao browser se for um usuário solicitando text/html ou a uma api solicitando application/json ou application/atom+xml por exemplo.
Não misturar o envelope do conteúdo com a questão de como retornar o erro, tem se falado que o em restful (atenção para o ful no final) se retornar sempre um conteúdo que tenha um padrão de hypermedia definido (para o bem das interwebs).
Dentre esses padrões, html é um, atom é outro, e mesmo coisas mais bizarras como http://www.amundsen.com/media-types/collection
Obs: Por questão de compatibilidade (e as vezes limitação de frameworks) o coneg tem sido feito com uso da “extensão” do arquivo, mas em API’s novas eu gosto de evitar esse tipo de coisa.