Description

As we drive towards consistency and consolidation, how we proactively communicate deprecation is increasingly important. We currently return a deprecation header for API endpoints and modules that are currently marked as deprecated. This header is an important machine readable indication that the endpoints may be disabled. However, we currently only return a date that specifies when the deprecation occurred. To make the header more helpful, we should include additional information about when the endpoint is expected to be sunset, as well as how to find more context about the motivation for deprecation and/or what the developer might need to do instead.

Conditions of acceptance

• Add a sunset date. Deprecation and sunsetting are separate concepts; although an endpoint is marked as deprecated, it is expected to continue working throughout the deprecation transition period. The sunset date is set in the future and communicates when the service is likely going to be turned off, rendering the endpoint unusable.
• Add support for a message field. This returns a human readable message in English. The purpose of this field is to provide additional context about the deprecation, including references to any relevant migration guides or other documentation that might help developers transition to an alternative solution.
• [Stretch] Add a messageTranslation property. This property returns the users' preferred language (vCurrent) or the explicitly requested (vNext) translations for the message. Returned values include default fallbacks if the preferred or requested language is not available.
• These properties may be set for the module as a whole, or on specific endpoints, through the REST framework.
• All new properties are optional and may be used in different combindations.
• Update deprecation documentation with more information about the deprecation header and how it will be used in API responses (Halley can do/help with this part)
• Update module creation guide with a note about how to use the individual fields and the recommended content (Halley can help with this)
• Demonstrate these fields in action by updating the messaging related to the mathoid deprecation (if it's already been deprecated; include these fields in the deprecation process if it's not already done): T431372: Mark Mathoid endpoints as deprecated

Implementation details

Related to suggestions outlined in T405038: [SPIKE] Propose an in-code mechanism for marking endpoints as deprecated and RFC9745
Suggested body outline is below:

deprecationSettings:
  from: timestamp // this already exists
  sunset: timestamp // Follow the same format as 'from' field; however, this is expected to be in the future
  message: string // This should always return an English version of what is ultimately a localisable string
  messageTranslations: 
    en: English version // always returned
    nl: Dutch version, for example // reflects the users' preferred language or the explicitly requested language