summary.md

Supported backends

sttp supports a number of synchronous and asynchronous backends. It's the backends that take care of managing connections, sending requests and receiving responses: sttp defines only the API to describe the requests to be send and handle the response data. Backends do all the heavy-lifting.

Choosing the right backend depends on a number of factors: whether you are using sttp to explore some data, or is it a production system; are you using a synchronous, blocking architecture or an asynchronous one; do you work mostly with Scala's Future, or maybe you use some form of a Task abstraction; finally, if you want to stream requests/responses, or not.

Which one to choose?

• for simple exploratory requests, use the synchronous HttpURLConnectionBackend
• if you have Akka in your stack, use Akka backend
• otherwise, if you are using Future, use the AsyncHttpClientFutureBackend Future backend
• finally, if you are using a functional effect wrapper, use one of the "functional" backends, for ZIO, Monix, Scalaz, cats-effect or fs2.

Each backend has three type parameters:

• F[_], the effects wrapper for responses. That is, when you invoke send() on a request description, do you get a Response[_] directly, or is it wrapped in a Future or a Task?
• S, the type of supported streams. If Nothing, streaming is not supported. Otherwise, the given type can be used to send request bodies or receive response bodies.
• WS_HANDLER, the type of supported websocket handlers. If NothingT, websockets are not supported. Otherwise, websocket connections can be opened, given an instance of the handler

Below is a summary of all the backends. See the sections on individual backend implementations for more information.

==================================== ============================ ================================================ ==================================================
Class                                Response wrapper             Supported stream type                            Supported websocket handlers
==================================== ============================ ================================================ ==================================================
``HttpURLConnectionBackend``         None (``Id``)                n/a                                              n/a
``TryHttpURLConnectionBackend``      ``scala.util.Try``           n/a                                              n/a
``AkkaHttpBackend``                  ``scala.concurrent.Future``  ``akka.stream.scaladsl.Source[ByteString, Any]`` ``akka.stream.scaladsl.Flow[Message, Message, _]``
``AsyncHttpClientFutureBackend``     ``scala.concurrent.Future``  n/a                                              ``sttp.client.asynchttpclient.WebSocketHandler``
``AsyncHttpClientScalazBackend``     ``scalaz.concurrent.Task``   n/a                                              ``sttp.client.asynchttpclient.WebSocketHandler``
``AsyncHttpClientZioBackend``        ``zio.IO``                   n/a                                              ``sttp.client.asynchttpclient.WebSocketHandler``
``AsyncHttpClientZioStreamsBackend`` ``zio.IO``                   ``zio.stream.Stream[Throwable, ByteBuffer]``     ``sttp.client.asynchttpclient.WebSocketHandler``
``AsyncHttpClientMonixBackend``      ``monix.eval.Task``          ``monix.reactive.Observable[ByteBuffer]``        ``sttp.client.asynchttpclient.WebSocketHandler``
``AsyncHttpClientCatsBackend``       ``F[_]: cats.effect.Async``  n/a                                              ``sttp.client.asynchttpclient.WebSocketHandler``
``AsyncHttpClientFs2Backend``        ``F[_]: cats.effect.Async``  ``fs2.Stream[F, ByteBuffer]``                    ``sttp.client.asynchttpclient.WebSocketHandler``
``OkHttpSyncBackend``                None (``Id``)                n/a                                              ``sttp.client.okhttp.WebSocketHandler``
``OkHttpFutureBackend``              ``scala.concurrent.Future``  n/a                                              ``sttp.client.okhttp.WebSocketHandler``
``OkHttpMonixBackend``               ``monix.eval.Task``          ``monix.reactive.Observable[ByteBuffer]``        ``sttp.client.okhttp.WebSocketHandler``
``Http4sBackend``                    ``F[_]: cats.effect.Effect`` ``fs2.Stream[F, Byte]``                          n/a
``HttpClientSyncBackend``            None (``Id``)                n/a                                              ``sttp.client.httpclient.WebSocketHandler``
``HttpClientFutureBackend``          ``scala.concurrent.Future``  n/a                                              ``sttp.client.httpclient.WebSocketHandler``
``HttpClientMonixBackend``           ``monix.eval.Task``          ``monix.reactive.Observable[ByteBuffer]``        ``sttp.client.httpclient.WebSocketHandler``
``FinagleBackend``                   ``com.twitter.util.Future``  n/a                                              n/a
==================================== ============================ ================================================ ==================================================

There are also backends which wrap other backends to provide additional functionality. These include:

• TryBackend, which safely wraps any exceptions thrown by a synchronous backend in scala.util.Try
• OpenTracingBackend, for OpenTracing-compatible distributed tracing. See the dedicated section.
• BraveBackend, for Zipkin-compatible distributed tracing. See the dedicated section.
• PrometheusBackend, for gathering Prometheus-format metrics. See the dedicated section.
• slf4j backends, for logging. See the dedicated section.

In additional there are also backends for JavaScript:

================================ ============================ ========================================= ============================
Class                            Response wrapper             Supported stream type                     Supported websocket handlers
================================ ============================ ========================================= ============================
``FetchBackend``                 ``scala.concurrent.Future``  n/a                                       n/a
``FetchMonixBackend``            ``monix.eval.Task``          ``monix.reactive.Observable[ByteBuffer]`` n/a
================================ ============================ ========================================= ============================

Finally, there are third-party backends:

• sttp-play-ws for "standard" play-ws (not standalone).
• akkaMonixSttpBackend, an Akka-based backend, but using Monix's Task & Observable.