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".
Date
valor en el mismo mensaje, el destinatario DEBE excluir el valor de advertencia. . . antes de . . . usando el mensaje ".