Convención para que el encabezado de respuesta HTTP notifique a los clientes de API obsoletas
Estoy actualizando nuestros endpoints de la API REST y quiero notificar a los clientes cuando están llamando al endpoint a ser obsoleto.
Qué encabezado debo usar en la respuesta con un mensaje como "Esta versión de la API está en desuso, consulte la documentación más reciente para actualizar sus puntos finales"
4 answers
No cambiaría nada en el código de estado para ser compatible con versiones anteriores. Añadiría un encabezado de "Advertencia" en la respuesta :
Warning: 299 - "Deprecated API"
También puede especificar el " - "con el" Agente " que emite la advertencia, y ser más explícito en el texto warn:
Warning: 299 api.blazingFrog.com "Deprecated API : use betterapi.blazingFrog.com instead. Old API maintained until 2015-06-02"
El encabezado de advertencia se especifica aquí: https://tools.ietf.org/html/rfc7234#section-5.5 . Warn-code 299 es genérico, "Obsoleto" no es estándar.
Debe decirle a sus clientes API que registren las advertencias HTTP y monitorearlo.
Nunca lo he usado hasta ahora, pero cuando mi empresa sea más madura en Rest API lo integraré.
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2017-03-06 14:29:04
Podrías usar 410 (Ido).
Así es como las Definiciones del Código de Estado del W3C lo describen:
410 (Desaparecido)
El recurso solicitado ya no está disponible en el servidor y no se conoce la dirección de reenvío. Se espera que esta condición sea considerado permanente. Los clientes con capacidades de edición de enlaces DEBEN elimine las referencias al URI de solicitud después de la aprobación del usuario. Si el servidor no sabe, o no tiene ninguna facilidad para determinar, si o no la condición es permanente, el código de estado 404 (No encontrado) DEBE ser usado en su lugar. Esta respuesta se puede almacenar en caché a menos que se indique lo contrario.
La respuesta 410 está destinada principalmente a ayudar a la tarea de web mantenimiento notificando al destinatario que el recurso es intencionalmente no disponible y que los propietarios del servidor desean que se eliminarán los enlaces remotos a ese recurso. Tal evento es común para de tiempo limitado, servicios promocionales y para los recursos pertenecientes a personas que ya no trabajan en el sitio del servidor. No lo es necesario para marcar todos los recursos permanentemente no disponibles como" gone " o para mantener la marca durante cualquier período de tiempo that que se deja a la discreción del propietario del servidor.
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2013-03-01 15:17:24
Yo habría ido con 301 (Se supone que los códigos de la serie 300 le dicen al cliente que tiene una acción que hacer.
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2012-12-14 18:20:47
Yo recomendaría un 207 Multi-Status respuesta, lo que indica que es una respuesta exitosa, pero también potencialmente tiene un segundo estado obsoleto.
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2017-03-16 21:14:23