Erro 404 na Web API REST/JSON – O que fazer?

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

https://api.dropbox.com/1/foo

{
    error: "Not Found"
}

Flickr

http://api.flickr.com/services/rest/?format=json&method=foo

jsonFlickrApi({
    "stat":"fail",
    "code":112,
    "message":"Method \"foo\" not found"
})

Google

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"

Facebook

https://graph.facebook.com/foo

{
   "error": {
      "message": "(#803) Some of the aliases you requested do not exist: foo",
      "type": "OAuthException",
      "code": 803
   }
}

Twitter

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 :)

https://api.twitter.com/1/foo

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.

— EOF —

Gostou desse texto? Aqui tem mais.