Estandarizar gestión de errores en las llamadas a la API

[koldLight]

Todas las funciones llaman actualmente a la API y no se tratan de forma especial los errores.

Sería bueno estandarizar esto con dos objetivos:

• Devolver de forma unificada los errores de timeout, 5xx, 4xx u otros, dando información suficiente al usuario de la API sobre lo ocurrido.
• Especificar la acción al encontrar un error, si debe saltar la excepción, o simplemente la salida debe ser algo vacío (un None, un dataframe vacío, un dict vacío, ... lo que más "pegue" con el tipo de dato devuelto en caso de salida correcta)

Aquí una buena referencia para definirlo.

[koldLight]

Cosas que estoy viendo:

reverse geocode

La API devuelve 200 para peticiones correctas, 204 para peticiones sin resultados (ya sea porque no lo encuentra como si no vienen los parámetros en la petición).

P.e. estas dos combinaciones de params dan 204 (no content) y la respuesta, una cadena vacía.

url = "http://www.cartociudad.es/geocoder/api/geocoder/reverseGeocode"
params = {"lat": 0, "lon": 0}
# params = {}
r = requests.get(url=url, params=params)
(r.status_code, r.text)

Y devuelve 404 si los tipos de dato son incorrectos:

url = "http://www.cartociudad.es/geocoder/api/geocoder/reverseGeocode"
params = {"lat": "asdas", "lon": "dasdf"}
r = requests.get(url=url, params=params)
(r.status_code, r.text)

geocode

La API devuelve 200 aunque no encuentre la localización (o el parámetro de dirección venga vacío). Estos dos casos devuelven 200 y la respuesta, 'callback([])'.

full_address = urllib.parse.quote("jaksfnsdfkjandkqnjkdasnkjnakj")
# full_address = urllib.parse.quote("")
url = f'http://www.cartociudad.es/geocoder/api/geocoder/findJsonp?q={full_address}'
r = requests.get(url)
(r.status_code, r.text)

Pero da un 500 si no le metes el parámetro. En principio esto no nos afecta porque siempre se lo estamos pasando.

route

La API devuelve 200 aunque no encuentre la ruta, aunque pone un parámetro de found: false para indicarlo. P.e.

base_url = f'http://www.cartociudad.es/services/api/route'
lat_init, lon_init, lat_dest, lon_dest = (0, 0, 0, 0)
vehicle = True
request_url = f'{base_url}?orig={lat_init},{lon_init}&dest={lat_init},{lon_dest}' \
              f'&locale=es&vehicle={"CAR" if vehicle else "WALK"}'

r = requests.get(request_url)
(r.status_code, r.text)

Devuelve 500 si metes cosas raras:

base_url = f'http://www.cartociudad.es/services/api/route'
lat_init, lon_init, lat_dest, lon_dest = ("a", "b", "c", "d")
vehicle = True
request_url = f'{base_url}?orig={lat_init},{lon_init}&dest={lat_init},{lon_dest}' \
              f'&locale=es&vehicle={"CAR" if vehicle else "WALK"}'

r = requests.get(request_url)
(r.status_code, r.text)

Conclusiones

Cada petición gestiona de una forma los errores, no parece que la API siempre devuelva los mismos status_code para los mismos tipos de error...

Sí parece que en general peta (con 500) si, cuando espera numéricos, le pasas otra cosa diferente.

Mis propuestas son:

• Utilizar type hints de python en las definiciones de las funciones para hacer explícitos los tipos de cada argumento (como en geocode
• En todas las funciones (geocode, reverse_geocode, etc...), si no se encuentra la dirección, la lat,lon, etc... la respuesta debería ser None / dict vacío, ... (lo más adecuado según la función), sin hacer saltar ninguna excepción.
• En todas las funciones (geocode, reverse_geocode, etc...), pueden ocurrir errores de la API no controlados (500, timeout, ...). Propongo que tengan un parámetro que sea error con posibles valores raise (por defecto) o ignore. Si se elige raise, saltará la excepción. Si se elige ignore, la función devuelve la salida más adecuada para un error (None, dict vacío, ...). Aquí no sé cuál sería la mejor forma, si hacer un raise_for_status (doc o una Exception genérica con info de si es 500, timeout o lo que sea (como en el link), u otra cosa... ¿qué opináis?

[koldLight]

Cierro esto, se quedan los comentarios de la issue como referencia, pero ya están creadas las tareas en otras issues