rest - protocolo - Convenio para el encabezado de respuesta HTTP para notificar a los clientes de API obsoleta
mozilla http headers (4)
Me hubiera / me hubiera ido con 301 (Movido permanentemente) Se supone que los códigos de la serie 300 le dicen al cliente que tienen una acción por hacer.
Estoy actualizando nuestros puntos finales REST API y quiero notificar a los clientes cuando están llamando al punto final "to-be-deprecated".
¿Qué encabezado debo usar en la respuesta con un mensaje en la línea de "Esta versión de la API está en desuso, consulte la documentación más reciente para actualizar sus puntos finales"
No cambiaría nada en el código de estado para ser compatible con versiones anteriores. Agregaría un encabezado de "Advertencia" en la respuesta:
Warning: 299 - "Deprecated API"
También puede especificar "-" con el "Agente" que emite la advertencia, y ser más explícito en el texto de advertencia:
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, "Deprecated" no es estándar.
Debe indicar a sus clientes API que registren las advertencias HTTP y que lo supervisen.
Nunca lo había usado hasta ahora, pero cuando mi empresa sea más madura en Rest API, lo integraré.
Podría usar 410 (Gone) .
Así es como lo describen las definiciones del código de estado del W3C:
410 (Ido)
El recurso solicitado ya no está disponible en el servidor y no se conoce ninguna dirección de reenvío. Se espera que esta condición se considere permanente. Los clientes con capacidades de edición de enlaces DEBERÍAN eliminar 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 la condición es permanente o no, el código de estado 404 (No encontrado) DEBE ser utilizado en su lugar. Esta respuesta es cacheable a menos que se indique lo contrario.
La respuesta 410 está destinada principalmente a ayudar a la tarea de mantenimiento web al notificar al destinatario que el recurso no está disponible intencionalmente y que los propietarios del servidor desean que se eliminen los enlaces remotos a ese recurso. Tal evento es común para los servicios de promoción por tiempo limitado y para los recursos que pertenecen a personas que ya no trabajan en el sitio del servidor. No es necesario marcar todos los recursos permanentemente no disponibles como "perdidos" o mantener la marca por un período de tiempo, eso queda a discreción del propietario del servidor.
Yo recomendaría una respuesta de 207 Multi-Status , que indica que es una respuesta exitosa, pero también tiene un segundo estado obsoleto.