Mantén estables las URLs de tus recursos y redirige las que se mueven

Trata cada URL que un agente pueda guardar como una promesa: mantenla funcionando, responde con una redirección permanente cuando el recurso se mueve y di 410 Gone cuando lo retiras.

Por qué

Los agentes guardan URLs: en archivos de memoria, en índices llms.txt, en el historial de tareas, en enlaces que citan a los usuarios y en los datos de entrenamiento de modelos que seguirán funcionando dentro de años. Reorganizar la documentación o renombrar un endpoint convierte todo eso en 404, y un 404 no le dice al agente si escribió mal la URL, si no tiene acceso o si debe buscar en otro lado. La nota del W3C de Tim Berners-Lee "Cool URIs don't change" (1998) plantea la regla: una URI buena es una que no cambia, un enlace roto le cuesta al dueño del servidor la confianza de quien lo sigue, y el trabajo del webmaster es asignar URIs que pueda sostener durante 2, 20 o 200 años. HTTP tiene señales para cuando el cambio no se puede evitar. El 308 Permanent Redirect de la RFC 9110 dice que el recurso tiene una URI permanente nueva y que las referencias futuras deberían usarla, y a diferencia del 301 conserva el método de la petición, algo que importa a un agente que envía un POST. El 410 Gone dice que el acceso ya no está disponible y que la situación probablemente es permanente, con el propósito declarado de que se eliminen los enlaces remotos, así que el agente puede descartar el enlace en vez de reintentar. AX-SYS-09 mapea tus recursos; este principio mantiene válidas en el tiempo las direcciones de ese mapa.

Haz

Construye las URLs alrededor de IDs estables, responde a las URLs movidas con 308 y un Location, y a las retiradas con 410 y una referencia a lo que las reemplazó.

No hagas

Renombrar rutas en un rediseño y dejar que los enlaces viejos caigan en 404, ni redirigir cada URL muerta a la página de inicio.

Artefacto

GET /docs/refund-api HTTP/1.1
-> 308 Permanent Redirect
Location: /docs/refunds

POST /v1/refunds/legacy_export HTTP/1.1
-> 410 Gone
Content-Type: application/problem+json
{ "title": "Retired on 2026-07-01", "replacement": "/v1/exports?type=refunds" }

El agente actualiza el enlace guardado después del 308 y deja de reintentar después del 410.