¿Cómo debe una API web manejar parámetros mal escritos / extra?

Pregunta: Para una API web pública (envíe solicitudes HTTP Get / Post, recupere datos JSON / XML), cómo deben manejarse los parámetros que están mal escritos o son extra.

Me parece que si se ignoran los parámetros incorrectos, un error en el código de la persona que llama puede pasar desapercibido ya que obtendrían un resultado válido. Esto puede ser especialmente cierto en situaciones en las que no sería obvio al observar los resultados devueltos.

Me refiero solo a parámetros opcionales. Obviamente, si un parámetro requerido está mal escrito, entonces el parámetro se considerará perdido y se devolverá un error.

Como ejemplo , la llamada a la API de Place Search tiene cuatro parámetros obligatorios (ubicación, radio, sensor y clave) y varios parámetros opcionales (los tipos son uno de ellos).

Puedo ejecutar estos comandos (con una clave API) y obtener 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"

El primer comando tiene el parámetro "tipos" en forma singular, que es un nombre de clave no válido. La API ignora ese parámetro y devuelve todos los tipos de entidades. En este caso, el error es obvio, pero puede haber ocasiones (y otras llamadas a la API) donde no lo será.

Ignorar parámetros adicionales es una práctica estándar. Es fácil escribir código como este

if (params.type) { 
  ... 
}

No vale la pena comprobar todos los parámetros pasados ​​para ver si alguno no es válido. Los errores ortográficos son el problema del cliente.

Si fuera un pequeño esfuerzo incluir una prueba de ortografía incorrecta para los nombres de los parámetros (¿cuánto trabajo desea hacer, verificando los nombres de TODOS los parámetros con una lista de los errores ortográficos más probables?), Podría hacerlo, pero normalmente recomendamos simplemente ignorar los parámetros adicionales que están mal escritos. Por supuesto, podría ser bueno si un servicio web devuelve un mensaje "No hay parámetro válido type, ¿quieres decir types?" pero solo si tiene el tiempo para implementarlo correctamente, y dado que generalmente no espero que ese tipo de mensaje regrese, no lo extrañaré si no está allí.

Creo que depende de cómo se especifique la API y de quién se haya hecho responsable de estos problemas. Si tuviera que diseñar una API, me gustaría asegurarme de que los parámetros correctos esperados (y sus valores asociados, si los hubiera) se manejan de la manera esperada o si hubo una entrada inesperada (como se requiere para proteger el método de datos extravagantes), se produjo la excepción adecuada o se devolvió el código de error.

Entonces diría que todas las entradas que no forman parte de las listas de parámetros esperados no son parte del problema de la API. Eso le permite ser específico y tomar posesión de una especificación muy definida y de cualquier persona que quiera usar que sea responsable de garantizar que la use correctamente.

Ha proporcionado una herramienta y un conjunto de instrucciones sobre cómo usarla. Haga que sea responsabilidad del usuario usarlo correctamente.