BAU Introduce setHeader and deprecate replaceHeader and addHeaders

README.md

@@ -80,12 +80,14 @@ httpClientV2.post(url"$url").withBody(Json.toJson(payload)).addHeaders(headers).
 
 #### Header manipulation
 
-With `HttpClient`, replacing a header can require providing a customised client implementation (e.g. to replace the user-agent header), or updating the `HeaderCarrier` (e.g. to replace the authorisation header). This can now all be done with the `replaceHeader` on `HttpClientV2` per call. e.g.
+With `HttpClient`, replacing a header can require providing a customised client implementation (e.g. to replace the user-agent header), or updating the `HeaderCarrier` (e.g. to replace the authorisation header). This can now all be done with the `setHeader` on `HttpClientV2` per call. e.g.
 
 ```scala
-httpClientV2.get(url"$url").replaceHeader("User-Agent" -> userAgent).replaceHeader("Authorization" -> authorization).execute[ResponseType]
+httpClientV2.get(url"$url").setHeader("User-Agent" -> userAgent).setHeader("Authorization" -> authorization).execute[ResponseType]
 ```
 
+As well as replacing existing header values, `setHeader` can be used to add new headers too, and in most cases should be used in preference to `addHeaders` where the values are merged with any existing ones (e.g. from HeaderCarrier).
+
 #### Using proxy
 
 With `HttpClient`, to use a proxy requires creating a new instance of HttpClient to mix in `WSProxy` and configure. With `HttpClientV2` this can be done with the same client, calling `withProxy` per call. e.g.

http-verbs-common/src/main/scala/uk/gov/hmrc/http/client/HttpClientV2.scala

@@ -61,8 +61,13 @@ trait RequestBuilder {
 
   // support functions
 
+  /** Adds the header. If the header has already been defined (e.g. from HeaderCarrier), it will be replaced. */
+  def setHeader(header: (String, String)): RequestBuilder
+
+  @deprecated("Use setHeader", "14.5.0")
   def replaceHeader(header: (String, String)): RequestBuilder
 
+  @deprecated("Use setHeader to add or replace, or use transform(_.addHttpHeaders) to append header values to existing", "14.5.0")
   def addHeaders(headers: (String, String)*): RequestBuilder
 
   def withProxy: RequestBuilder

http-verbs-common/src/main/scala/uk/gov/hmrc/http/client/HttpClientV2Impl.scala

@@ -111,9 +111,12 @@ final class RequestBuilderImpl(
     request.withHttpHeaders(denormalise(hdrsWithoutKey) :+ header : _*)
   }
 
-  override def replaceHeader(header: (String, String)): RequestBuilderImpl =
+  override def setHeader(header: (String, String)): RequestBuilderImpl =
     transform(replaceHeaderOnRequest(_, header))
 
+  override def replaceHeader(header: (String, String)): RequestBuilderImpl =
+    setHeader(header)
+
   override def addHeaders(headers: (String, String)*): RequestBuilderImpl =
     transform(_.addHttpHeaders(headers: _*))
 

http-verbs-common/src/test/scala/uk/gov/hmrc/http/client/HttpClientV2Spec.scala

@@ -531,7 +531,7 @@ class HttpClientV2Spec
         httpClientV2
           .put(url"$wireMockUrl/")
           .transform(_.withBody(Json.toJson(ReqDomain("req"))))
-          .replaceHeader("User-Agent" -> "ua2")
+          .setHeader("User-Agent" -> "ua2")
           .execute[ResDomain]
     }
 
@@ -547,7 +547,7 @@ class HttpClientV2Spec
         httpClientV2
           .put(url"$wireMockUrl/")
           .withBody(Json.toJson(ReqDomain("req")))
-          .replaceHeader("User-Agent" -> "ua2")
+          .setHeader("User-Agent" -> "ua2")
           .execute[ResDomain]
 
       res.futureValue shouldBe ResDomain("res")