Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README #160

Merged
merged 3 commits into from
Mar 5, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ The default implicits for `HttpReads` have been deprecated. There are new implic
```scala
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:
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 appropriate. The differences are:
* You will have to explicitly state the type of the response - it will not resolve to `HttpResponse` if none is specified. (i.e. `GET(url)` will now be `GET[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:
```scala
Expand Down
46 changes: 42 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ It encapsulates some common concerns for calling other HTTP services on the HMRC

## Migration

See [CHANGELOG](https://github.com/hmrc/http-verbs/blob/master/CHANGELOG.md) for changes and migrations.
See [CHANGELOG](CHANGELOG.md) for changes and migrations.

## Adding to your build

Expand All @@ -37,7 +37,7 @@ There are two HttpClients available.

### uk.gov.hmrc.http.HttpClient

Examples can be found [here](https://github.com/hmrc/http-verbs/blob/master/http-verbs-test-common/src/test/scala/uk/gov/hmrc/http/examples/Examples.scala)
Examples can be found [here](http-verbs-test-play-30/src/test/scala/uk/gov/hmrc/http/examples/Examples.scala)

URLs can be supplied as either `java.net.URL` or `String`. We recommend supplying `java.net.URL` and using the provided [URL interpolator](#url-interpolator) for correct escaping of query and path parameters.

Expand All @@ -51,7 +51,7 @@ In addition, it:
- Exposes the underlying `play.api.libs.ws.WSRequest` with `transform`, making it easier to customise the request.
- Only accepts the URL as `java.net.URL`; you can make use of the provided [URL interpolator](#url-interpolator).

Examples can be found in [here](/http-verbs-common/src/test/scala/uk/gov/hmrc/http/client/HttpClientV2Spec.scala)
Examples can be found in [here](http-verbs-play-30/src/test/scala/uk/gov/hmrc/http/client/HttpClientV2Spec.scala)

To migrate:

Expand Down Expand Up @@ -180,7 +180,7 @@ For external hosts, headers should be provided explicitly to the VERB function (
client.GET(url"https://externalhost/api", headers = Seq("Authorization" -> "Bearer token"))(hc) //explicit Authorization header for external request
```

Internal hosts are identified with the configuration [internalServiceHostPatterns](/http-verbs-common/src/main/resources/reference.conf) The headers which are forwarded, to _internal hosts_, include all the headers modelled explicitly in the `HeaderCarrier`, plus any that are listed with the configuration `bootstrap.http.headersAllowlist`.
Internal hosts are identified with the configuration [internalServiceHostPatterns](http-verbs-play-30/src/main/resources/reference.conf) The headers which are forwarded, to _internal hosts_, include all the headers modelled explicitly in the `HeaderCarrier`, plus any that are listed with the configuration `bootstrap.http.headersAllowlist`.
For example, if you want to pass headers to stubs, you can use the following override for your service: `internalServiceHostPatterns= "^.*(stubs?).*(\.mdtp)$"`

When providing additional headers to http requests, if it corresponds to an explicit one on the HeaderCarrier, it is recommended to replace it, otherwise you will be sending it twice:
Expand All @@ -193,6 +193,44 @@ For all other headers, provide them to the VERB function:
client.GET(url = url"https://internalhost/api", headers = Seq("AdditionHeader" -> "AdditionalValue"))(hc)
```

### Deserialising Response

The Response is deserialised by an instance of [HttpReads](http-verbs-play-30/src/main/scala/uk/gov/hmrc/http/HttpReads.scala).

You can either create your own instances or use the provided instances with

```scala
import uk.gov.hmrc.http.HttpReads.Implicits._
```

The default implicits (without explicit import) have been deprecated. See [here](CHANGELOG.md#version-1100) for more details.

The `HttpReads` describes how to convert a `HttpResponse` into your model using the status code and response body.

The [provided instances](http-verbs-play-30/src/main/scala/uk/gov/hmrc/http/HttpReadsInstances.scala), brought into scope with the above import, allow you to:

- Request raw HttpResponse:
```scala
client.GET[HttpResponse](url)
```
- Convert the response body from Json using a play json reads:
```scala
implicit val reads: Reads[MyModel] = ???
client.get[MyModel](url)
```
Note this instance will return failed Futures with `UpstreamErrorResponse` for non-success status codes. Json parsing failures will similarly be returned as `JsValidationException` These exceptions can be recovered from if required.
- Handle 404s with `None`
```scala
implict val reads: Reads[MyModel] = ???
client.get[Option[MyModel]](url)
```
- Return non-success status codes as `UpstreamErrorResponse` in `Either`
```scala
implict val reads: Reads[MyModel] = ???
client.get[Either[UpstreamErrorResponse, MyModel]](url)
```


## Testing

In your SBT build add the following in your test dependencies:
Expand Down
10 changes: 5 additions & 5 deletions project/LibDependencies.scala
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@ import sbt._

object LibDependencies {

val play28Version = "2.8.20"
val play29Version = "2.9.0"
val play30Version = "3.0.0"
val play28Version = "2.8.21"
val play29Version = "2.9.2"
val play30Version = "3.0.2"

// Dependencies for http-verbs-common and http-verbs-play-xxx modules
def coreCompileCommon(scalaVersion: String) = Seq(
Expand All @@ -25,13 +25,13 @@ object LibDependencies {
)

val coreCompilePlay29 = Seq(
"com.typesafe.play" %% "play-json" % "2.10.2", // version provided by play29Version
"com.typesafe.play" %% "play-json" % "2.10.4", // version provided by play29Version
"org.slf4j" % "slf4j-api" % "2.0.9",
"com.typesafe.play" %% "play-ahc-ws" % play29Version
)

val coreCompilePlay30 = Seq(
"org.playframework" %% "play-json" % "3.0.0", // version provided by play30Version
"org.playframework" %% "play-json" % "3.0.2", // version provided by play30Version
"org.slf4j" % "slf4j-api" % "2.0.9",
"org.playframework" %% "play-ahc-ws" % play30Version
)
Expand Down