O que lançamos este mês: geocodificação, IP, fuso horário e mais
Um resumo do trabalho recente em toda a API: novos hosts de compatibilidade, consultas de fuso horário e altitude mais rápidas, recursos no painel e mais visibilidade sobre a cota.
Um formato de erro mais limpo em todos os endpoints
Uma resposta de erro não é uma nota de rodapé de uma API: ela faz parte do contrato do qual toda integração depende, tanto quanto uma resposta de sucesso. Padronizamos o formato de erro em todos os endpoints nativos do My Geocode, para que uma falha tenha a mesma aparência independentemente de qual parte da API a gerou.
Seja uma requisição que falha por falta de um parâmetro, uma chave inválida, uma cota esgotada ou uma coordenada malformada, a resposta segue uma estrutura única e previsível. Essa consistência significa que o código de tratamento de erros escrito uma vez, para um endpoint, funciona da mesma forma em todos os outros endpoints nativos, sem precisar de uma lógica de tratamento separada para cada um.
Falhas relacionadas à cota merecem uma menção especial, já que são o tipo mais comum que uma integração ativa vai encontrar. Quando uma requisição ultrapassaria a cota de uma chave ou de uma rede, a resposta deixa isso claro, e os cabeçalhos de cota já presentes em toda resposta, X-Quota-Limit, X-Quota-Used, X-Quota-Free-Remaining e os demais, informam exatamente quanto espaço havia disponível antes da requisição que falhou. Essa combinação permite que um cliente diferencie um problema de cota de um problema de autenticação ou de uma requisição inválida apenas pela resposta, sem adivinhar.
Os hosts de compatibilidade são uma exceção deliberada a essa padronização, e por um bom motivo. Todo o propósito deles é reproduzir exatamente o formato de requisição e de resposta de outro provedor, e isso inclui a aparência dos erros. Uma requisição no formato do Bing Maps REST Services que falha continua recebendo um erro no próprio formato de erro do Bing, porque reproduzir esse formato com precisão, em caso de sucesso ou de falha, é todo o sentido de um host compatível (drop-in). Padronizar os erros ali quebraria justamente a compatibilidade que o host existe para oferecer.
Para tudo o que for construído sobre nossos endpoints nativos, esse formato mais limpo deve tornar o tratamento de erros visivelmente mais simples de escrever e manter. Uma única rotina de parsing, um único conjunto de campos esperados e um comportamento consistente em /v1/forward, /v1/reverse, /v1/ip, /v1/timezone, /v1/elevation, /v1/autocomplete e /v1/postcode.
A documentação completa do formato de erro, incluindo nomes de campos e causas comuns, está disponível em /docs/errors/. Se a sua integração tem hoje ramificações separadas de tratamento de erros para diferentes endpoints nativos, este é um bom momento para simplificar tudo em uma só.