API REST con Spring MVC

Una aplicación web siempre acaba teniendo clientes que no son navegadores. Una aplicación móvil, un panel de control en React, un script de importación nocturno, un socio que sincroniza su catálogo. Ninguno de estos clientes quiere HTML: quieren datos y una forma fiable de saber si la operación ha tenido éxito.

El reflejo habitual consiste en devolver JSON desde los controladores existentes y dar el trabajo por terminado. Ahí es donde nacen las API mal diseñadas, y el síntoma es siempre el mismo: todo responde 200. Un recurso inexistente devuelve 200 con un cuerpo null. Una validación fallida devuelve 200 con un campo "erreur" en el JSON. Una excepción devuelve 200 con un cuerpo vacío. El cliente ya no puede decidir nada de forma automática; tiene que inspeccionar el contenido para adivinar qué ha pasado, y cada cliente lo adivina de forma distinta.

El código de estado HTTP no es una decoración: es el único canal que todos los clientes, todas las bibliotecas HTTP y todos los intermediarios de red entienden sin ninguna convención previa. Un 404 lo trata correctamente una caché, un 429 provoca un nuevo intento en un cliente bien escrito, un 201 con una cabecera Location indica dónde se encuentra el recurso creado. Devolver 200 en todas partes es renunciar a usar un protocolo que ya se está pagando.