diff options
author | adamw <adam@warski.org> | 2017-10-12 19:23:09 +0200 |
---|---|---|
committer | adamw <adam@warski.org> | 2017-10-12 19:23:09 +0200 |
commit | 7bf4d02da823c21b27cf20ba0b764b511ac69432 (patch) | |
tree | 04b9ab557c4af82b9970af386e6f4f9e4292e472 /docs/backends | |
parent | 7885188a982c193e26f8ca6bc9aea8f6a642b32d (diff) | |
download | sttp-7bf4d02da823c21b27cf20ba0b764b511ac69432.tar.gz sttp-7bf4d02da823c21b27cf20ba0b764b511ac69432.tar.bz2 sttp-7bf4d02da823c21b27cf20ba0b764b511ac69432.zip |
More docs
Diffstat (limited to 'docs/backends')
-rw-r--r-- | docs/backends/akkahttp.rst | 52 | ||||
-rw-r--r-- | docs/backends/asynchttpclient.rst | 82 | ||||
-rw-r--r-- | docs/backends/custom.rst | 19 | ||||
-rw-r--r-- | docs/backends/httpurlconnection.rst | 9 | ||||
-rw-r--r-- | docs/backends/okhttp.rst | 17 |
5 files changed, 179 insertions, 0 deletions
diff --git a/docs/backends/akkahttp.rst b/docs/backends/akkahttp.rst new file mode 100644 index 0000000..41e3a7c --- /dev/null +++ b/docs/backends/akkahttp.rst @@ -0,0 +1,52 @@ +``AkkaHttpBackend`` +=================== + +To use, add the following dependency to your project:: + + "com.softwaremill.sttp" %% "akka-http-backend" % "0.0.20" + +This backend depends on `akka-http <http://doc.akka.io/docs/akka-http/current/scala/http/>`_. +A fully **asynchronous** backend. Sending a request returns a response wrapped +in a ``Future``. + +Next you'll need to add an implicit value:: + + implicit val sttpBackend = AkkaHttpBackend() + + // or, if you'd like to use an existing actor system: + implicit val sttpBackend = AkkaHttpBackend.usingActorSystem(actorSystem) + +This backend supports sending and receiving +`akka-streams <http://doc.akka.io/docs/akka/current/scala/stream/index.html>`_ +streams of type ``akka.stream.scaladsl.Source[ByteString, Any]``. + +To set the request body as a stream:: + + import com.softwaremill.sttp._ + import com.softwaremill.sttp.akkahttp._ + + import akka.stream.scaladsl.Source + import akka.util.ByteString + + val source: Source[ByteString, Any] = ... + + sttp + .streamBody(source) + .post(uri"...") + +To receive the response body as a stream:: + + import com.softwaremill.sttp._ + import com.softwaremill.sttp.akkahttp._ + + import akka.stream.scaladsl.Source + import akka.util.ByteString + + implicit val sttpBackend = AkkaHttpBackend() + + val response: Future[Response[Source[ByteString, Any]]] = + sttp + .post(uri"...") + .response(asStream[Source[ByteString, Any]]) + .send() + diff --git a/docs/backends/asynchttpclient.rst b/docs/backends/asynchttpclient.rst new file mode 100644 index 0000000..cd359b1 --- /dev/null +++ b/docs/backends/asynchttpclient.rst @@ -0,0 +1,82 @@ +``AsyncHttpClientBackend`` +========================== + +To use, add the following dependency to your project:: + + "com.softwaremill.sttp" %% "async-http-client-backend-future" % "0.0.20" + // or + "com.softwaremill.sttp" %% "async-http-client-backend-scalaz" % "0.0.20" + // or + "com.softwaremill.sttp" %% "async-http-client-backend-monix" % "0.0.20" + // or + "com.softwaremill.sttp" %% "async-http-client-backend-cats" % "0.0.20" + +This backend depends on `async-http-client <https://github.com/AsyncHttpClient/async-http-client>`_. +A fully **asynchronous** backend, which uses `Netty <http://netty.io>`_ behind the +scenes. + +The responses are wrapped depending on the dependency chosen in either a: + +* standard Scala ``Future`` +* `Scalaz <https://github.com/scalaz/scalaz>`_ ``Task``. There's a transitive dependency on ``scalaz-concurrent``. +* `Monix <https://monix.io`_ ``Task``. There's a transitive dependency on ``monix-eval``. +* Any type implementing the `Cats Effect <https://github.com/typelevel/cats-effect>`_ ``Async`` typeclass, such as ``cats.effect.IO``. There's a transitive dependency on ``cats-effect``. + +Next you'll need to add an implicit value:: + + implicit val sttpBackend = AsyncHttpClientFutureBackend() + + // or, if you're using the scalaz version: + implicit val sttpBackend = AsyncHttpClientScalazBackend() + + // or, if you're using the monix version: + implicit val sttpBackend = AsyncHttpClientMonixBackend() + + // or, if you're using the cats effect version: + implicit val sttpBackend = AsyncHttpClientCatsBackend[cats.effect.IO]() + + // or, if you'd like to use custom configuration: + implicit val sttpBackend = AsyncHttpClientFutureBackend.usingConfig(asyncHttpClientConfig) + + // or, if you'd like to instantiate the AsyncHttpClient yourself: + implicit val sttpBackend = AsyncHttpClientFutureBackend.usingClient(asyncHttpClient) + +Streaming using Monix +--------------------- + +The Monix backend supports streaming (as both Monix and Async Http Client +support reactive streams ``Publisher``s out of the box). The type of +supported streams in this case is ``Observable[ByteBuffer]``. That is, you can +set such an observable as a request body:: + + import com.softwaremill.sttp._ + + import java.nio.ByteBuffer + import monix.reactive.Observable + + val obs: Observable[ByteBuffer] = ... + + sttp + .streamBody(obs) + .post(uri"...") + +And receive responses as an observable stream:: + + import com.softwaremill.sttp._ + import com.softwaremill.sttp.asynchttpclient.monix._ + + import java.nio.ByteBuffer + import monix.eval.Task + import monix.reactive.Observable + + implicit val sttpBackend = AsyncHttpClientMonixBackend() + + val response: Task[Response[Observable[ByteBuffer]]] = + sttp + .post(uri"...") + .response(asStream[Observable[ByteBuffer]]) + .send() + +It's also possible to use `fs2 <https://github.com/functional-streams-for-scala/fs2>`_ +streams for sending request & receiving responses. + diff --git a/docs/backends/custom.rst b/docs/backends/custom.rst new file mode 100644 index 0000000..86d750a --- /dev/null +++ b/docs/backends/custom.rst @@ -0,0 +1,19 @@ +Custom backends, logging, metrics +================================= + +It is also entirely possible to write your own backend (if so, please consider +contributing!) or wrapping an existing one. You can even write completely +generic wrappers for any delegate backend, as each backend comes equipped +with a monad for the response type. This brings the possibility to ``map`` and +``flatMap`` over responses. + +Possible use-cases for wrapper-backend include: + +* logging +* capturing metrics +* request signing (transforming the request before sending it to the delegate) + +To pass some context to wrapper-backends, requests can be *tagged*. Each +``RequestT`` instance contains a ``tags: Map[String, Any]`` field. This is unused +by http, but can be used e.g. to pass a metric name or logging context. + diff --git a/docs/backends/httpurlconnection.rst b/docs/backends/httpurlconnection.rst new file mode 100644 index 0000000..a196343 --- /dev/null +++ b/docs/backends/httpurlconnection.rst @@ -0,0 +1,9 @@ +``HttpURLConnectionBackend`` +============================ + +The default **synchronous** backend. Sending a request returns a response wrapped +in the identity type constructor, which is equivalent to no wrapper at all. + +To use, add an implicit value:: + + implicit val sttpBackend = HttpURLConnectionBackend() diff --git a/docs/backends/okhttp.rst b/docs/backends/okhttp.rst new file mode 100644 index 0000000..52fbc49 --- /dev/null +++ b/docs/backends/okhttp.rst @@ -0,0 +1,17 @@ +``OkHttpClientBackend`` +======================= + +To use, add the following dependency to your project:: + + "com.softwaremill.sttp" %% "okhttp-backend" % "0.0.20" + // or, for the monix version: + "com.softwaremill.sttp" %% "okhttp-backend-monix" % "0.0.20" + +This backend depends on `OkHttp <http://square.github.io/okhttp/>`_, and offers: + +* a **synchronous** backend: ``OkHttpSyncBackend`` +* an **asynchronous**, ``Future``-based backend: ``OkHttpFutureBackend`` +* an **asynchronous**, Monix-``Task``-based backend: ``OkHttpMonixBackend`` + +OkHttp fully supports HTTP/2. + |