http-verbs is a Scala library providing an interface to make asynchronous HTTP calls.
It encapsulates some common concerns for calling other HTTP services on the HMRC Tax Platform, including:
- Logging
- Header Carrier
- Http Transport
- Core Http function interfaces
- executing hooks
- mapping errors
- Auditing
- Logging
- Propagation of common headers
- Response handling, converting failure status codes into a consistent set of exceptions - allows failures to be * automatically propagated to the caller
- Request & Response de-serializations
The fields authProvider ('ap'), userId and token are no longer available in the session and these names have been removed from SessionKeys object.
The fields token and userId are no longer available in the session and so have been removed from HeaderCarrier
The configuration key httpHeadersWhitelist has been replaced with bootstrap.http.headersAllowlist. httpHeadersWhitelist will no longer take effect.
The default implicits for HttpReads have been deprecated. There are new implicits, which need to be pulled in explicitly with
import uk.gov.hmrc.http.HttpReads.Implicits._The behaviour of the predefined implicits are not quite the same as the deprecated ones, and you are encouraged to define your own HttpReads if none are apropriate. The differences are:
- You will have to explicitly state the type of the response - it will not resolve to
HttpResponseif none is specified. (i.e.GET(url)will now beGET[HttpResponse](url)). It is deemed better to be explicit since the type will dictate how errors are handled. - The default
HttpRead[HttpResponse]will no longer throw an exception if there is a non-2xx status code. Since the HttpResponse already encodes errors, it expects you will handle this yourself. To get the behaviour similar to previous (see Exceptions for differences), use:
implicit val legacyRawReads = HttpReads.throwOnFailure(HttpReads.readEither)HttpReads[Option[A]]only returns None for 404, and will try to parse other responses. Previously, 204 was also treated as None, consider representing this with Unit instead.- The
HttpReads[A]whereAis defined by aplay.api.libs.json.Reads[A]works in the same way as before, i.e. throws exceptions for non-2xx response codes (UpstreamErrorResponse), and json parsing errors (JsValidationException). Since the http-verbs API operates withinFuture, this is probably the simplest response type, since Future offers recovery, and if not handled, will propagate to the caller. However the HttpReads can be combined with other HttpReads to return the errors in different ways. E.g.HttpReads[Either[UpstreamErrorResponse, JsResult[A]]]HttpReads[Try[JsResult[A]]], These error encoded types are available for any response type not just json
The trait for HttpResponse will be replaced with a case class. You should only create instances with the HttpResponse.apply function, and not extend it.
If your clients previously relied on an instance of WSHttpResponse being returned, they will have to change to use the HttpResponse abstraction.
The new HttpReads instances only return UpstreamErrorResponse for failures returned from upstream services. They will no longer return HttpException which will be reserved for problems in making the request (e.g. GatewayTimeoutException for timeout exceptions and BadGatewayException for connect exceptions), and originate in the service itself.
The trait UpstreamErrorResponse will be replaced with a case class, and the subclasses Upstream4xxResponse and Upstream5xxResponse have been deprecated in preparation. If you need to pattern match on these types, use UpstreamErrorResponse.Upstream4xxResponse and UpstreamErrorResponse.Upstream5xxResponse instead.
In your SBT build add:
resolvers += Resolver.bintrayRepo("hmrc", "releases")
libraryDependencies += "uk.gov.hmrc" %% "http-verbs-play-xx" % "x.x.x"Where play-xx is play-25, play-26 or play-27 depending on your version of Play.
Play 2.5 examples can be found here
Play 2.6 and 2.7 examples can be found here
The ResponseMatchers class provides some useful logic for testing http-related code.
In your SBT build add the following in your test dependencies:
libraryDependencies += "uk.gov.hmrc" %% "http-verbs-test-play-xx" % "x.x.x" % TestThis code is open source software licensed under the Apache 2.0 License.