Merge pull request #151 from hmrc/MTDSA-21817

Added deprecated and sunset header

Author: AhmadZNaeem

app/api/controllers/RequestHandler.scala

@@ -22,11 +22,16 @@ import api.models.errors.{ErrorWrapper, InternalError}
 import api.models.outcomes.ResponseWrapper
 import api.services.ServiceOutcome
 import cats.data.EitherT
-import cats.implicits._
+import cats.data.Validated.Valid
+import cats.implicits.*
+import config.AppConfig
+import config.Deprecation.Deprecated
 import play.api.http.Status
 import play.api.libs.json.{JsValue, Writes}
 import play.api.mvc.Result
 import play.api.mvc.Results.InternalServerError
+import routing.Version
+import utils.DateUtils.longDateTimestampGmt
 import utils.Logging
 
 import scala.concurrent.{ExecutionContext, Future}
@@ -36,7 +41,8 @@ trait RequestHandler {
   def handleRequest()(implicit
       ctx: RequestContext,
       request: UserRequest[?],
-      ec: ExecutionContext
+      ec: ExecutionContext,
+      appConfig: AppConfig
   ): Future[Result]
 
 }
@@ -61,7 +67,7 @@ object RequestHandler {
       auditHandler: Option[AuditHandler] = None
   ) extends RequestHandler {
 
-    def handleRequest()(implicit ctx: RequestContext, request: UserRequest[?], ec: ExecutionContext): Future[Result] =
+    def handleRequest()(implicit ctx: RequestContext, request: UserRequest[?], ec: ExecutionContext, appConfig: AppConfig): Future[Result] =
       Delegate.handleRequest()
 
     def withErrorHandling(errorHandling: ErrorHandling): RequestHandlerBuilder[Input, Output] =
@@ -113,14 +119,26 @@ object RequestHandler {
     // Scoped as a private delegate so as to keep the logic completely separate from the configuration
     private object Delegate extends RequestHandler with Logging with RequestContextImplicits {
 
-      implicit class Response(result: Result) {
+      implicit class Response(result: Result)(implicit appConfig: AppConfig, apiVersion: Version) {
+
+        private def withDeprecationHeaders: List[(String, String)] = {
+
+          appConfig.deprecationFor(apiVersion) match {
+            case Valid(Deprecated(deprecatedOn, maybeSunsetDate)) =>
+              List(
+                "Deprecation" -> longDateTimestampGmt(deprecatedOn),
+                "Link"        -> appConfig.apiDocumentationUrl
+              ) ++ maybeSunsetDate.map(sunsetDate => "Sunset" -> longDateTimestampGmt(sunsetDate))
+            case _ => Nil
+          }
+        }
 
         def withApiHeaders(correlationId: String, responseHeaders: (String, String)*): Result = {
           val headers =
             responseHeaders ++
               List(
                 "X-CorrelationId" -> correlationId
-              )
+              ) ++ withDeprecationHeaders
 
           result.copy(header = result.header.copy(headers = result.header.headers ++ headers))
         }
@@ -130,7 +148,8 @@ object RequestHandler {
       def handleRequest()(implicit
           ctx: RequestContext,
           request: UserRequest[?],
-          ec: ExecutionContext
+          ec: ExecutionContext,
+          appConfig: AppConfig
       ): Future[Result] = {
 
         logger.info(
@@ -157,8 +176,11 @@ object RequestHandler {
       private def handleSuccess(parsedRequest: Input, serviceResponse: ResponseWrapper[Output])(implicit
           ctx: RequestContext,
           request: UserRequest[?],
-          ec: ExecutionContext
+          ec: ExecutionContext,
+          appConfig: AppConfig
       ): Result = {
+        implicit val apiVersion: Version = Version(request)
+
         logger.info(
           s"[${ctx.endpointLogContext.controllerName}][${ctx.endpointLogContext.endpointName}] - " +
             s"Success response received with CorrelationId: ${ctx.correlationId}")
@@ -174,8 +196,11 @@ object RequestHandler {
       private def handleFailure(errorWrapper: ErrorWrapper)(implicit
           ctx: RequestContext,
           request: UserRequest[?],
-          ec: ExecutionContext
+          ec: ExecutionContext,
+          appConfig: AppConfig
       ): Result = {
+        implicit val apiVersion: Version = Version(request)
+
         logger.warn(
           s"[${ctx.endpointLogContext.controllerName}][${ctx.endpointLogContext.endpointName}] - " +
             s"Error response received with CorrelationId: ${ctx.correlationId}")

app/config/AppConfig.scala

@@ -16,12 +16,18 @@
 
 package config
 
+import cats.data.Validated
+import cats.implicits.catsSyntaxValidatedId
 import com.typesafe.config.Config
+import config.Deprecation.{Deprecated, NotDeprecated}
 import play.api.{ConfigLoader, Configuration}
 import routing.Version
 import uk.gov.hmrc.auth.core.ConfidenceLevel
 import uk.gov.hmrc.play.bootstrap.config.ServicesConfig
 
+import java.time.LocalDateTime
+import java.time.format.{DateTimeFormatter, DateTimeFormatterBuilder}
+import java.time.temporal.ChronoField
 import javax.inject.{Inject, Singleton}
 
 trait AppConfig {
@@ -72,6 +78,10 @@ trait AppConfig {
   def endpointsEnabled(version: Version): Boolean
   def endpointsEnabled(version: String): Boolean
 
+  def apiDocumentationUrl: String
+
+  def deprecationFor(version: Version): Validated[String, Deprecation]
+
   def apiVersionReleasedInProduction(version: String): Boolean
 
   def endpointReleasedInProduction(version: String, name: String): Boolean
@@ -84,6 +94,9 @@ trait AppConfig {
 
 @Singleton
 class AppConfigImpl @Inject() (config: ServicesConfig, val configuration: Configuration) extends AppConfig {
+  // API name
+  val appName: String = config.getString("appName")
+
   // MTD ID Lookup Config
   val mtdIdBaseUrl: String = config.baseUrl(serviceName = "mtd-id-lookup")
 
@@ -118,8 +131,52 @@ class AppConfigImpl @Inject() (config: ServicesConfig, val configuration: Config
   def endpointsEnabled(version: Version): Boolean = config.getBoolean(s"api.${version.name}.endpoints.enabled")
   def endpointsEnabled(version: String): Boolean  = config.getBoolean(s"api.$version.endpoints.enabled")
 
+  private val DATE_FORMATTER = new DateTimeFormatterBuilder()
+    .append(DateTimeFormatter.ofPattern("yyyy-MM-dd"))
+    .parseDefaulting(ChronoField.HOUR_OF_DAY, 23)
+    .parseDefaulting(ChronoField.MINUTE_OF_HOUR, 59)
+    .parseDefaulting(ChronoField.SECOND_OF_MINUTE, 59)
+    .toFormatter()
+
+  def deprecationFor(version: Version): Validated[String, Deprecation] = {
+    val isApiDeprecated: Boolean = apiStatus(version) == "DEPRECATED"
+
+    val deprecatedOn: Option[LocalDateTime] =
+      configuration
+        .getOptional[String](s"api.$version.deprecatedOn")
+        .map(value => LocalDateTime.parse(value, DATE_FORMATTER))
+
+    val sunsetDate: Option[LocalDateTime] =
+      configuration
+        .getOptional[String](s"api.$version.sunsetDate")
+        .map(value => LocalDateTime.parse(value, DATE_FORMATTER))
+
+    val isSunsetEnabled: Boolean =
+      configuration.getOptional[Boolean](s"api.$version.sunsetEnabled").getOrElse(true)
+
+    if (isApiDeprecated) {
+      (deprecatedOn, sunsetDate, isSunsetEnabled) match {
+        case (Some(dO), Some(sD), true) =>
+          if (sD.isAfter(dO))
+            Deprecated(dO, Some(sD)).valid
+          else
+            s"sunsetDate must be later than deprecatedOn date for a deprecated version $version".invalid
+        case (Some(dO), None, true) => Deprecated(dO, Some(dO.plusMonths(6))).valid
+        case (Some(dO), _, false)   => Deprecated(dO, None).valid
+        case _                      => s"deprecatedOn date is required for a deprecated version $version".invalid
+      }
+
+    } else NotDeprecated.valid
+
+  }
+
   def apiVersionReleasedInProduction(version: String): Boolean = config.getBoolean(s"api.$version.endpoints.api-released-in-production")
 
+  def apiDocumentationUrl: String =
+    configuration
+      .getOptional[String]("api.documentation-url")
+      .getOrElse(s"https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/$appName")
+
   def safeEndpointsEnabled(version: String): Boolean =
     configuration
       .getOptional[Boolean](s"api.$version.endpoints.enabled")

app/config/Deprecation.scala

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2025 HM Revenue & Customs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package config
+
+import java.time.LocalDateTime
+
+sealed trait Deprecation
+
+object Deprecation {
+  case object NotDeprecated extends Deprecation
+
+  case class Deprecated(deprecatedOn: LocalDateTime, sunsetDate: Option[LocalDateTime]) extends Deprecation
+
+}

app/definition/ApiDefinitionFactory.scala

@@ -16,6 +16,7 @@
 
 package definition
 
+import cats.data.Validated.Invalid
 import config.AppConfig
 import play.api.Logger
 import routing.{Version, Version1, Version2}
@@ -58,6 +59,7 @@ class ApiDefinitionFactory @Inject() (appConfig: AppConfig) {
     )
 
   private[definition] def buildAPIStatus(version: Version): APIStatus = {
+    checkDeprecationConfigFor(version)
     APIStatus.parser
       .lift(appConfig.apiStatus(version))
       .getOrElse {
@@ -66,4 +68,9 @@ class ApiDefinitionFactory @Inject() (appConfig: AppConfig) {
       }
   }
 
+  private def checkDeprecationConfigFor(version: Version): Unit = appConfig.deprecationFor(version) match {
+    case Invalid(error) => throw new Exception(error)
+    case _              => ()
+  }
+
 }

app/routing/Versions.scala

@@ -22,6 +22,9 @@ import play.api.mvc.RequestHeader
 
 object Version {
 
+  def apply(request: RequestHeader): Version =
+    Versions.getFromRequest(request).getOrElse(throw new Exception("Missing or unsupported version found in request accept header"))
+
   object VersionWrites extends Writes[Version] {
 
     def writes(version: Version): JsValue = version match {

app/utils/DateUtils.scala

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2025 HM Revenue & Customs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package utils
+
+import java.time.format.DateTimeFormatter
+import java.time.{LocalDateTime, ZoneId}
+import java.util.Locale
+
+object DateUtils {
+
+  def longDateTimestampGmt(dateTime: LocalDateTime): String = longDateTimeFormatGmt.format(dateTime)
+
+  private val longDateTimeFormatGmt: DateTimeFormatter = DateTimeFormatter
+    .ofPattern("EEE, dd MMM yyyy HH:mm:ss z", Locale.ENGLISH)
+    .withZone(ZoneId.of("GMT"))
+
+}

test/api/controllers/ControllerBaseSpec.scala

@@ -17,18 +17,22 @@
 package api.controllers
 
 import api.controllers.ControllerTestRunner.validNino
+import api.mocks.MockIdGenerator
 import api.models.audit.{AuditError, AuditEvent, AuditResponse, GenericAuditDetail}
+import api.models.auth.UserDetails
 import api.models.errors.MtdError
 import api.services.{MockAuditService, MockEnrolmentsAuthService, MockMtdIdLookupService}
-import config.RealAppConfig
+import cats.implicits.catsSyntaxValidatedId
+import config.Deprecation.NotDeprecated
+import config.{AppConfig, MockAppConfig, RealAppConfig}
 import play.api.http.{HeaderNames, MimeTypes, Status}
 import play.api.libs.json.{JsValue, Json}
-import play.api.mvc.{AnyContentAsEmpty, ControllerComponents, Result}
+import play.api.mvc.{AnyContent, AnyContentAsEmpty, ControllerComponents, Result}
 import play.api.test.Helpers.stubControllerComponents
 import play.api.test.{FakeRequest, ResultExtractors}
+import routing.{Version, Version2}
 import support.UnitSpec
 import uk.gov.hmrc.http.HeaderCarrier
-import api.mocks.MockIdGenerator
 
 import scala.concurrent.Future
 
@@ -39,9 +43,13 @@ abstract class ControllerBaseSpec
     with HeaderNames
     with ResultExtractors
     with MockAuditService
-    with ControllerSpecHateoasSupport {
+    with ControllerSpecHateoasSupport
+    with MockAppConfig {
+
+  implicit val apiVersion: Version = Version2
 
-  implicit lazy val fakeRequest: FakeRequest[AnyContentAsEmpty.type] = FakeRequest()
+  implicit lazy val fakeRequest: FakeRequest[AnyContentAsEmpty.type] =
+    FakeRequest().withHeaders(HeaderNames.ACCEPT -> s"application/vnd.hmrc.${apiVersion.name}+json")
 
   lazy val cc: ControllerComponents = stubControllerComponents()
 
@@ -52,6 +60,11 @@ abstract class ControllerBaseSpec
   def fakePostRequest[T](body: T): FakeRequest[T] = fakeRequest.withBody(body)
 
   def fakePutRequest[T](body: T): FakeRequest[T] = fakeRequest.withBody(body)
+
+  private val userDetails                           = UserDetails("mtdId", "Individual", Some("agentReferenceNumber"))
+  implicit val userRequest: UserRequest[AnyContent] = UserRequest[AnyContent](userDetails, fakeRequest)
+  implicit val appConfig: AppConfig                 = mockAppConfig
+
 }
 
 trait ControllerTestRunner extends MockEnrolmentsAuthService with MockMtdIdLookupService with MockIdGenerator with RealAppConfig {
@@ -70,6 +83,7 @@ trait ControllerTestRunner extends MockEnrolmentsAuthService with MockMtdIdLooku
     MockedMtdIdLookupService.lookup(nino).returns(Future.successful(Right("test-mtd-id")))
     MockedEnrolmentsAuthService.authoriseUser()
     MockIdGenerator.generateCorrelationId.returns(correlationId)
+    MockedAppConfig.deprecationFor(apiVersion).returns(NotDeprecated.valid).anyNumberOfTimes()
 
     protected def runOkTest(expectedStatus: Int, maybeExpectedResponseBody: Option[JsValue] = None): Unit = {
       val result: Future[Result] = callController()

test/api/controllers/DocumentationControllerSpec.scala

@@ -17,15 +17,14 @@
 package api.controllers
 
 import com.typesafe.config.ConfigFactory
+import config.rewriters.*
 import config.rewriters.DocumentationRewriters.CheckAndRewrite
-import config.rewriters._
 import config.{MockAppConfig, RealAppConfig}
 import controllers.{AssetsConfiguration, DefaultAssetsMetadata, RewriteableAssets}
-import definition._
+import definition.*
 import play.api.http.{DefaultFileMimeTypes, DefaultHttpErrorHandler, FileMimeTypesConfiguration, HttpConfiguration}
 import play.api.mvc.Result
 import play.api.{Configuration, Environment}
-import routing.{Version, Versions}
 import uk.gov.hmrc.http.HeaderCarrier
 
 import scala.concurrent.ExecutionContext.Implicits.global
@@ -35,11 +34,6 @@ class DocumentationControllerSpec extends ControllerBaseSpec with MockAppConfig
 
   private val apiVersionName = s"$latestEnabledApiVersion.0"
 
-  protected val apiVersion: Version =
-    Versions
-      .getFrom(apiVersionName)
-      .getOrElse(fail(s"Matching Version object not found for $apiVersionName"))
-
   private val titleLineMatcher = """(.*title:.*)""".r
   private val titleMatcher     = """^(\s*title:\s*".*?\s*\[test\sonly]).*$""".r