Como uma API da web deve lidar com parâmetros com erros ortográficos / extras?

Pergunta: Para uma API da web voltada ao público (envie solicitações HTTP Get / Post, obtenha dados JSON / XML de volta), como devem ser tratados os parâmetros com erros de ortografia ou extras.

Parece-me que, se os parâmetros incorretos forem ignorados, um erro no código do chamador poderá passar despercebido, pois eles receberiam um resultado válido. Isso pode ser especialmente verdadeiro em situações em que não seria óbvio observando os resultados retornados.

Estou me referindo apenas a parâmetros opcionais. Obviamente, se um parâmetro necessário estiver incorreto, o parâmetro será considerado ausente e um erro será retornado.

Como exemplo , a chamada da API da Pesquisa de local tem quatro parâmetros obrigatórios (local, raio, sensor e chave) e vários parâmetros opcionais (tipos é um deles).

Eu posso executar estes comandos (com uma chave de API) e recuperar resultados válidos:

curl "https://maps.googleapis.com/maps/api/place/search/json?location=45.47554,-122.794189&radius=500&sensor=false&key=<api_key>&type=bakery"

curl "https://maps.googleapis.com/maps/api/place/search/json?location=45.47554,-122.794189&radius=500&sensor=false&key=<api_key>&types=bakery"

O primeiro comando possui o parâmetro "types" no formato singular, que é um nome de chave inválido. A API ignora esse parâmetro e retorna todos os tipos de entidades. Nesse caso, o erro é óbvio, mas pode haver momentos (e outras chamadas de API) em que não haverá.

Ignorar parâmetros extras é uma prática padrão. É fácil escrever código como este

if (params.type) { 
  ... 
}

Não vale a pena verificar todos os parâmetros passados ​​para ver se algum deles é inválido. Erros de ortografia são o problema do cliente.

Se fosse um pequeno esforço incluir um teste de ortografia incorreta para nomes de parâmetros (quanto trabalho você deseja fazer, verificando os nomes de TODOS os parâmetros em relação a uma lista de erros ortográficos mais prováveis?), Eu poderia fazê-lo, mas normalmente faria recomendamos apenas ignorar os parâmetros extras que estão incorretos. Obviamente, pode ser bom se um WebService enviar de volta uma mensagem "Nenhum parâmetro válido type, você quis dizer types?" mas apenas se você tiver tempo para implementá-lo corretamente e, como normalmente não espero que esse tipo de mensagem volte, não sentirei falta se não estiver lá.

Eu acho que depende de como a API é especificada e de quem foi responsável por esses problemas. Se eu fosse projetar uma API, assumiria a responsabilidade de garantir que os parâmetros corretos esperados (e seus valores associados, se houver) fossem manipulados da maneira esperada ou se houvesse entrada inesperada (conforme necessário para proteger o método de dados malucos), a exceção apropriada foi lançada ou o código de erro foi retornado.

Eu diria que todas as entradas que não fazem parte das listas de parâmetros esperadas não fazem parte do problema da API. Isso permite que você seja específico e se apóie em uma especificação muito definida e quem quiser usá-lo é responsável por garantir que o use adequadamente.

Você forneceu uma ferramenta e um conjunto de instruções sobre como usá-lo. Torne responsabilidade do usuário usá-lo corretamente.