Pruebas de API REST: las convenciones que conviene verificar

Las pruebas de API REST empiezan por la semántica de los códigos de estado

REST asigna un significado a los códigos de estado y los clientes dependen de ese significado. Conviene verificarlo de forma explícita en lugar de darlo por hecho.

• 201 con una ubicación al crear, no 200 con un cuerpo y nada más.

• 404 si no existe, 403 si está prohibido. Devolver 404 cuando el acceso está prohibido es una decisión deliberada que toman algunos equipos; devolver 403 para algo que no existe es sencillamente un error.

• 422 o 400 para entradas no válidas, de forma consistente. Elige uno y comprueba que todos los endpoints coincidan.

• Nunca 200 con un error dentro del cuerpo. Es habitual y obliga a cada cliente a escribir un manejo especial.

Idempotencia

Se supone que PUT y DELETE son idempotentes. Llamarlos dos veces debería dejar el mismo estado y no producir un error la segunda vez. Es fácil equivocarse en esto y fácil de comprobar: llama dos veces y verifica.

Lo mismo vale para un segundo DELETE que devuelve 404 en lugar de 500. Los clientes reintentan, y un endpoint que no tolera reintentos convierte un corte de red momentáneo en un fallo visible para el usuario.

Las convenciones que tu servicio dice seguir

La comprobación que está detrás de todas

Verifica el cuerpo, no solo el estado. Un 200 con una lista vacía donde debería haber un registro pasa cualquier verificación de estado que se haya escrito jamás. Este único hábito detecta más defectos reales en las pruebas de API REST que cualquier comprobación de convenciones.

Los cuatro problemas

Cuatro cosas deciden si una suite de pruebas de API sobrevive a su primer año: sesiones que caducan, valores que solo existen en tiempo de ejecución, llamadas que dependen unas de otras y registros que nadie limpia. TestSprite las resuelve con Auto-Authentication, Dynamic Variables, Dependency Chains y Auto-Cleanup, descritos en la documentación de pruebas de API.

Las convenciones que conviene poner por escrito primero

Antes de probar si tu API sigue sus convenciones, alguien tiene que decir cuáles son, y la mayoría de los equipos descubre en ese ejercicio que no están de acuerdo.

Cuatro preguntas resuelven casi todo. ¿Qué estado devuelve una creación y viene con una ubicación? ¿Un recurso inexistente es 404 o 403 cuando quien llama tampoco tendría permiso para verlo? ¿Un parámetro de consulta desconocido se rechaza o se ignora? ¿PATCH trata un campo ausente como sin cambios o como null?

Ninguna de ellas tiene una respuesta universalmente correcta y todas son decisiones de las que dependen tus clientes. Escribir las cuatro respuestas lleva veinte minutos y convierte la vaga intención de ser RESTful en algo que de verdad puedes verificar, que es el requisito previo para poder probarlo.

Conseguir cobertura sin escribirla toda

Los planes generados cubren las categorías funcional, de esquema, de autorización, de manejo de errores y de límites a partir de una especificación o de una pasada de descubrimiento, lo que incluye por defecto la mayoría de las comprobaciones de convenciones anteriores.

Si prefieres no instalar nada, el panel hace lo mismo. Todo lo demás que puede hacer la línea de comandos está en el repositorio del CLI.

Si el pipeline pertenece a otro equipo, la GitHub App es el camino de menor resistencia: es un webhook, no cambia nada en tu repositorio y se dispara cuando tu build informa que la nueva versión está publicada. Si prefieres que la comprobación quede visible en el repositorio, un paso de GitHub Actions hace justo eso.

Cómo verifica TestSprite las convenciones

Los planes generados cubren las categorías funcional, de esquema, de autorización, de manejo de errores y de límites contra el servicio en ejecución, lo que incluye la mayoría de las comprobaciones de convenciones anteriores: la semántica de estados por operación, el rechazo de entradas no válidas, el comportamiento ante un recurso inexistente y una paginación que cuadra.

Auto-Authentication mantiene las sesiones activas durante toda la ejecución, Dynamic Variables traslada valores de una llamada a otra, Dependency Chains deduce el orden de ejecución a partir de lo que cada caso necesita y produce, y Auto-Cleanup elimina exactamente lo que creó la ejecución. Esto último importa más en REST de lo que se suele pensar, porque comprobar la idempotencia implica llamar dos veces a propósito a la misma operación destructiva.

Lo que obtienes es que tus propias convenciones se verifican en cada cambio, en lugar de quedar documentadas y a la espera de que se cumplan, que es lo que evita que un endpoint devuelva 200 en silencio donde todos los demás devuelven 201.