From 5aaac06c2d5ea122470ee7b27277ac0747e767d1 Mon Sep 17 00:00:00 2001 From: adamw Date: Wed, 19 Jul 2017 14:45:11 +0200 Subject: How the response should be handled is now part of the request definition --- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 23 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 93ace05..8c0de51 100644 --- a/README.md +++ b/README.md @@ -11,16 +11,17 @@ import com.softwaremill.sttp._ val sort: Option[String] = None val query = "http language:scala" -// the `query` parameter is automatically url-encoded and `sort` removed +// the `query` parameter is automatically url-encoded +// `sort` is removed, as the value is not defined val request = sttp.get(uri"https://api.github.com/search/repositories?q=$query&sort=$sort") -// response body is read into a string, no need to remember to consume it later -val response = request.send(responseAsString("utf-8")) +implicit val handler = HttpURLConnectionSttpHandler +val response = request.send() // response.header(...): Option[String] println(response.header("Content-Length")) -// response.body: String as specified when sending the request +// response.body: by default read into a String println(response.body) ``` @@ -97,14 +98,14 @@ request: ```scala implicit val handler = HttpConnectionSttpHandler -val response: Response[String] = request.send(responseAsString) +val response: Response[String] = request.send() ``` -Note that when sending the request, we have to specify how to read the response -body. That way, you don't need to remember to consume it later, avoiding a -potential resource leak. Response bodies can be ignored (`ignoreResponseBody`), -read into a parameter sequence (`responseAsParams`) and more; some backends -also support request & response streaming. +By default the response body is read into a utf-8 string. How the response body +is handled is also part of the request description. The body can be ignore +(`.response(ignore)`), read into a sequence of parameters +(`.response(asParams)`) and more; some backends also support request & response +streaming. The default handler doesn't wrap the response into any container, but other asynchronous handlers might do so. The type parameter in the `Response[_]` @@ -210,7 +211,7 @@ import akka.util.ByteString val source: Source[ByteString, Any] = ... sttp - .body(source) + .streamBody(source) .post(uri"...") ``` @@ -218,6 +219,7 @@ To receive the response body as a stream: ```scala import com.softwaremill.sttp._ +import com.softwaremill.sttp.akkahttp._ import akka.stream.scaladsl.Source import akka.util.ByteString @@ -227,21 +229,39 @@ implicit val sttpHandler = new AkkaHttpSttpHandler(actorSystem) val response: Future[Response[Source[ByteString, Any]]] = sttp .post(uri"...") - .send(responseAsStream[Source[ByteString, Any]]) + .response(asStream[Source[ByteString, Any]]) + .send() ``` -## Request types +## Request type + +All request descriptions have type `RequestT[U, T, S]` (T as in Template). +If this looks a bit complex, don't worry, what the three type parameters stand +for is the only thing you'll hopefully have to remember when using the API! + +Going one-by-one: -All requests have type `RequestTemplate[U]`, where `U[_]` specifies if the -request method and URL are specified. There are two type aliases for the -request template that are used: +* `U[_]` specifies if the request method and URL are specified. Using the API, +this can be either `type Empty[X] = None`, meaning that the request has neither +a method nor an URI. Or, it can be `type Id[X] = X` (type-level identity), +meaning that the request has both a method and an URI specified. Only requests +with a specified URI & method can be sent. +* `T` specifies the type to which the response will be read. By default, this +is `String`. But it can also be e.g. `Array[Byte]` or `Unit`, if the response +should be ignored. Response body handling can be changed by calling the +`.response` method. With backends which support streaming, this can also be +a supported stream type. +* `S` specifies the stream type that this request uses. Most of the time this +will be `Nothing`, meaning that this request does not send a streaming body +or receive a streaming response. So most of the times you can just ignore +that parameter. But, if you are using a streaming backend and want to +send/receive a stream, the `.streamBody` or `response(asStream[S])` will change +the type parameter. -* `type Request = RequestTemplate[Id]`, where `type Id[X] = X` is the identity, -meaning that the request has both a method and an URI specified. Such a request -can be sent. -* `type PartialRequest = RequestTemplate[Empty]`, where `type Empty[X] = None`, -meaning that the request has neither a method nor an URI. Both of these fields -will be set to `None` (the `Option` subtype). Such a request cannot be sent. +There are two type aliases for the request template that are used: + +* `type Request[T, S] = RequestT[Id, T, S]`. A sendable request. +* `type PartialRequest[T, S] = RequestT[Empty, T, S]` ## Notes @@ -269,4 +289,9 @@ will be set to `None` (the `Option` subtype). Such a request cannot be sent. * [dispatch](http://dispatch.databinder.net/Dispatch.html) * [play ws](https://github.com/playframework/play-ws) * [fs2-http](https://github.com/Spinoco/fs2-http) -* [http4s](http://http4s.org/v0.17/client/) \ No newline at end of file +* [http4s](http://http4s.org/v0.17/client/) + +## Credits + +* [Tomasz Szymański](https://github.com/szimano) +* [Adam Warski](https://github.com/adamw) \ No newline at end of file -- cgit v1.2.3