Convención para el encabezado de respuesta HTTP para notificar a los clientes sobre API obsoletas

84

Estoy actualizando nuestros puntos finales de la API REST y quiero notificar a los clientes cuando estén llamando al punto final que quedará obsoleto.
¿Qué encabezado debo usar en la respuesta con un mensaje del tipo "Esta versión de API está obsoleta? Consulte la documentación más reciente para actualizar sus puntos finales".

rest http http-status-codes deprecation-warning Rana Ardiente
fuente

Respuestas:

72

No cambiaría nada en el código de estado para que sea compatible con versiones anteriores. Agregarí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 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 decirle a sus clientes API que registren las advertencias HTTP y las monitoreen.

Nunca lo he usado hasta ahora, pero cuando mi empresa esté más madura en Rest API, lo integraré.

Editar (2019-04-25): como lo mencionó @Harry Wood, el encabezado de Advertencia está en un capítulo relacionado con el almacenamiento en caché en la documentación. Sin embargo, el RFC es claroWarnings can be used for other purposes, both cache-related and otherwise.

Si prefiere un método alternativo, este borrador https://tools.ietf.org/html/draft-dalal-deprecation-header-00 sugiere un nuevo encabezado "Desactivación".

BenC
fuente
1
La fecha de advertencia al final del valor de advertencia no tiene ningún propósito aquí, y es mejor omitirla, o corre el riesgo de confundir a los clientes: “Si un destinatario. . . recibe una fecha de advertencia que es diferente del Datevalor en el mismo mensaje, el destinatario DEBE excluir el valor de advertencia. . . antes de . . . usando el mensaje ".
Vasiliy Faronov
Si no incluye el advertir a la fecha, se debe tener el formato de la misma manera como el Dateencabezado: "Thu, 02 Apr 2015 12:25:32 GMT".
Vasiliy Faronov
@VasiliyFaronov: tienes razón, porque en ese caso (API obsoleta) este mensaje de advertencia siempre será cierto en el futuro. Entonces, si la respuesta (con el mensaje de advertencia) es enviada por un caché en un proxy y la fecha del mensaje es diferente, la advertencia se ignorará, mientras que seguirá siendo válida. Edito la respuesta
BenC
¿No está ese encabezado de "advertencia" relacionado con el almacenamiento en caché? Quiero decir que en el enlace de su documentación menciona el almacenamiento en caché, pero también todo el documento RFC parece estar relacionado con el almacenamiento en caché. Pero el Warningencabezado se ve bien como un lugar de texto libre para describir la desaprobación. Los encabezados Deprecationy Sunsetmencionados en otras respuestas, parecerían ser una solución estándar emergente para describir la desaprobación de una manera más estricta y potencialmente legible por máquina.
Harry Wood
1
WarningEl encabezado no está relacionado solo con cachés. La primera oración de la Warningsección es "Las advertencias se pueden utilizar para otros fines, tanto relacionados con la caché como de otro tipo".
Çelebi Murat
37

Podrías usar 410 (ido) .

Así es como lo describen las Definiciones de códigos de estado del W3C :

410 (desaparecido)

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 DEBEN eliminar las referencias al Request-URI después de la aprobación del usuario. Si el servidor no sabe, o no tiene la posibilidad de determinar, si la condición es permanente o no, el código de estado 404 (No encontrado) DEBE usarse en su lugar. Esta respuesta se puede almacenar en caché a menos que se indique lo contrario.

La respuesta 410 tiene como objetivo principal ayudar en la tarea de mantenimiento web notificando 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 servicios promocionales por tiempo limitado y para recursos que pertenecen a personas que ya no trabajan en el sitio del servidor. No es necesario marcar todos los recursos que no estén disponibles permanentemente como "desaparecidos" o mantener la marca durante un período de tiempo; eso queda a discreción del propietario del servidor.

Emanuil Rusev
fuente
36
El problema con 410 es que no cumple con el requisito de "ser obsoleto" ... Funciona bien cuando la API se ha ido, pero no es que se vaya a acabar en el futuro .
Julien Genestoux
3
Si devuelve 410, romperá su compatibilidad con versiones anteriores
BenC
4
410 Goneno se trata de obsolescencia, se trata de un método ya no disponible. Como dijo @BenC, la mejor manera es usar el encabezado de advertencia
sempasha
2
Esta podría ser la siguiente fase de la API obsoleta
Shiplu Mokaddim
16

Me habría ido con 301 (movido permanentemente) Se supone que los códigos de la serie 300 le dicen al cliente que tiene una acción que hacer.

u07ch
fuente
4
Eso es probablemente lo que usaré una vez que se elimine el punto final, pero quiero darles la oportunidad de ser notificados por algún tiempo (asumiendo que verán los encabezados HTTP en la respuesta) para que puedan hacer los cambios necesarios en su fin.
BlazingFrog
2
Realmente no hay un estado para moverse. 302 (El recurso solicitado reside temporalmente en otra ubicación, pero aún se puede encontrar en el URI solicitado.) ...
u07ch
1
No estoy buscando un estado, sino un encabezado "estándar" para agregar a la respuesta.
BlazingFrog
1
No hay un encabezado estándar para este tipo de respuesta. Debe crear un encabezado propio y describirlo en la documentación de su propia api.
Brian Kelly
Creo que se supone que cualquier código de respuesta> = 300 rompe cosas. 299 permitirá a los clientes mantener viva su aplicación hasta que se desactive la API mientras realizan los cambios necesarios.
devlord
6

Recomendaría una 207 Multi-Statusrespuesta, indicando que es una respuesta exitosa, pero también potencialmente tiene un segundo estado obsoleto.

typeoneerror
fuente
1
Interesante. No sabía nada de eso, pero creo que en la práctica existe un gran peligro de que introduzcas un cambio importante para algunos clientes al cambiar a un código de respuesta diferente, incluso si todavía está en el rango 200. Supongo que podría hacer una especie de aumento suave de la presión. Comience con un Deprecationencabezado (que los clientes probablemente ignorarán desafortunadamente), luego use este código 207, luego 301 se movió y finalmente 410 desapareció.
Harry Wood
4

Refinando la respuesta de @dret. Hay dos encabezados HTTP relevantes para la desaprobación: Deprecation( https://tools.ietf.org/html/draft-dalal-deprecation-header-00 ) y Sunset.

Para informar a los usuarios sobre la desactivación planificada, se Deprecationdebe utilizar el encabezado HTTP. Esto indica que el punto final se eliminará en algún momento en el futuro. También le permite indicar la fecha en que se anunció y describir recursos alternativos.

Para informar a los usuarios sobre la fecha de caducidad planificada del recurso en desuso, se Sunsetdebe utilizar el encabezado además del encabezado Desactivación. Esto se describe en la sección # 5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5 .

El borrador n. ° 11 https://tools.ietf.org/html/draft-wilde-sunset-header-11 del Sunsetencabezado aclara este aspecto también en la sección 1.4 https://tools.ietf.org/html/draft-wilde -sunset-header-11 # sección-1.4 .

sdatspun2
fuente
3

Hay un campo de encabezado HTTP llamado Sunsetque está destinado a señalar una próxima desaprobación de un recurso. https://tools.ietf.org/html/draft-wilde-sunset-header se encuentra en las últimas etapas para convertirse en un RFC. Idealmente, su API debería documentar lo que va a utilizar Sunset, para que los clientes puedan buscarla y actuar en consecuencia, si así lo desean.

triste
fuente