Desarrollo de códigos de error y respuestas de API | Juana Suau | noviembre 2022

Foto de Markus Liste en Unsplash

Cada solicitud de API tiene una respuesta de API. El código de estado que recibe como parte de la respuesta indica si la solicitud que acaba de enviar se realizó correctamente. A su vez, el código de error le permite saber que su solicitud falló.

Los códigos de error y estado son extremadamente importantes para todas las partes involucradas. Permiten a los creadores de API comunicarse con los usuarios de API de manera breve y eficiente, ya que siempre se devuelven códigos en cada respuesta.

En cierto sentido, esta es la primera etapa de la comunicación directa incluso antes de que se cree un ticket de soporte. Si el código de error contiene un mensaje suficientemente descriptivo o bien documentado, es muy probable que no se requiera el ticket y que el usuario pueda solucionar el problema por sí mismo.

Si la API utiliza códigos de estado de respuesta HTTP estándar, esta puede ser la primera indicación para el usuario de la API de dónde está el problema y cómo solucionarlo. Y así, por ejemplo, todos 5xx los errores indican algunos problemas con el servidor, mientras que 3xx sugiere un problema con la URL.

Los códigos de estado de éxito son tan importantes como los códigos de error. Sin ellos, sería muy difícil para un usuario de API saber si su solicitud para actualizar o eliminar un recurso fue exitosa.

En las pautas oficiales del protocolo HTTP, todos los códigos de estado están organizados en clases para simplificar la administración de la API. Por lo tanto, si acaba de enviar una solicitud POST o PUT, lo más probable es que obtenga 201 Createdrespuesta como una indicación estándar de que su solicitud fue exitosa y el recurso fue creado/actualizado como resultado. Este tipo de respuestas pertenecen al grupo de respuestas exitosas. También puede recibir información de redirección o mensajes que resulten del comportamiento estándar de la API.

Cuando se trata de códigos de error, como se mencionó anteriormente, generalmente se devuelven errores del cliente o del servidor. Este es un excelente punto de partida para saber de dónde proviene el problema, ya sea del sistema externo al que está enviando la solicitud (servidor) o de su propio entorno (cliente).

Los códigos de error pueden ser increíblemente útiles si se muestran o documentan correctamente. Los que se devuelven en el paso de respuesta de pasar los datos de la API son las primeras puertas de comunicación directa que los desarrolladores pueden establecer con el usuario final (también conocido como el compañero desarrollador que finalmente implementa su API).

Los códigos de error notifican al usuario sobre una falla específica, pero los mensajes de error bien pensados ​​también pueden acelerar el proceso de solución de problemas al brindarle al usuario ideas sobre qué hacer cuando ocurre un error de este tipo o a quién contactar si todo lo demás falla.

¡No es el consumidor de la API quien elige el error, sino el creador de la API! Y pueden usarlo a su favor. No trates los errores como un mal necesario, trátalos como un medio de comunicación.

Al principio, el código de error estándar le dirá dónde ocurrió el error y cuáles fueron las circunstancias. Por ejemplo, el error estándar 401 Unauthorized le dirá de inmediato que, independientemente del recurso que intente solicitar, no tiene credenciales de autenticación válidas.

Si el mensaje especificado incluye además un mensaje corto, por ejemplo, Pass valid token, también puede aprender un poco más sobre esta API en particular y su comportamiento esperado. Aprenderá que esto requiere un token, que debe pasarse como parte de la solicitud.

La cantidad mínima de palabras en un mensaje de error de este tipo agrega un valor tremendo para el consumidor de la API.

Por supuesto, a menudo el código de error que utiliza no es tan completo como el código de error. 401 Unauthorized o 404 Not Found. Entonces, ¿cómo lo hace más amigable para los humanos y le da al desarrollador la capacidad de solucionar los problemas por su cuenta?

El aspecto más importante del código de error es brindarle contexto. Este contexto generalmente se pasa en el cuerpo de la respuesta, que puede agregar.

Si bien las solicitudes GET se explican por sí mismas, obtienes un recurso o no lo obtienes. Las solicitudes PUT y POST son un poco más complicadas porque está modificando los datos contenidos en el recurso. Debido a esto, es natural que generen posibles errores más complejos.

Agregar un poco de contexto a la respuesta del cuerpo del error será de gran ayuda. Digamos nuestro estándar 400 Bad Request puede proporcionar información adicional. Ya sabemos que la solicitud fue alterada en el lado del cliente, pero en lugar de rascarse la cabeza y entrecerrar los ojos para ver la pantalla para averiguar qué salió mal, se le puede informar al desarrollador cuál fue el problema.

El contexto importa mucho y debe ser valioso. En lugar de escribir sobre lo que no se puede hacer, a veces es más útil escribir sobre lo que se puede hacer. Por ejemplo, en lugar de escribir un mensaje:

Invalid file type

puede especificar qué tipo de archivo se debe usar en su lugar:

Only supports csv file types.

Los códigos de error deben tratarse como documentación y deben mantenerse y actualizarse como parte del proceso de administración de la API. Cada vez que cambie su API, considere si el código de error cambia o evoluciona junto con él.

Con eso en mente, el mismo código de error podría haberse escrito teniendo en cuenta las obstrucciones del servicio y, en su lugar, decir:

Only supports the following file types: csv.

De esa manera, cada vez que agregue soporte para un tipo de familia diferente, puede simplemente agregarlo a la lista en lugar de volver a escribir todo el mensaje de error.

Es importante recordar la regla general de que no debe incluir demasiada información en el código de error para no abrumar al usuario.

Una sugerencia es suficiente, y si desea agregar más, remita a sus usuarios a la documentación donde puede agregar más información. Un buen ejemplo es la referencia de la API de Stripe, donde incluyen enlaces a sus códigos de error al describir lo que se devuelve en la respuesta, o la API de Infobip, donde hay un enlace a la documentación del código de estado y error en el cuerpo de la respuesta, que encuentro más útil para la API. consumidor. Lo que me falta es la misma práctica con posibles mensajes de error.

Es difícil desarrollar buenas prácticas de notificación de errores que cubran todos los escenarios posibles, todos los dispositivos y todas las audiencias. Es importante usar métodos ya estandarizados que ya transmitan mucha información, así que siéntase libre de usar grupos de códigos HTTP para comenzar.

Cuando piense en los códigos de error, tenga la mente abierta acerca de la experiencia del usuario, son una parte importante y, como se mencionó anteriormente, la primera forma de comenzar a comunicarse con sus usuarios.

Previous post Todo sobre accesibilidad y significado: términos por Don Norman, UX Pioneer | Radhika Arora | noviembre 2022
Next post Estrategia de contenidos 101

Deja una respuesta