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, or HttpClientSyncBackend if you are on Java11.
• 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 JVM backends; see the sections on individual backend implementations for more information:

==================================== ============================ ================================================= ==================================================
Class                                Response wrapper             Supported stream type                             Supported websocket handlers
==================================== ============================ ================================================= ==================================================
``HttpURLConnectionBackend``         None (``Identity``)          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.Task``                 ``zio.stream.Stream[Throwable, Byte]``            ``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, Byte]``                           ``sttp.client.asynchttpclient.WebSocketHandler``
``OkHttpSyncBackend``                None (``Identity``)          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 (``Identity``)          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``
``HttpClientZioBackend``             ``zio.RIO[Blocking, *]``     ``zio.stream.ZStream[Blocking, Throwable, Byte]`` ``sttp.client.httpclient.WebSocketHandler``
``FinagleBackend``                   ``com.twitter.util.Future``  n/a                                               n/a
==================================== ============================ ================================================= ==================================================

The backends work with Scala 2.11, 2.12 and 2.13 (with some exceptions for 2.11). Moreover, HttpURLConnectionBackend, AsyncHttpClientFutureBackend, AsyncHttpClientZioBackend, HttpClientSyncBackend, HttpClientFutureBackend and HttpClientZioBackend are additionally built with Dotty (Scala 3).

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.
• PrometheusBackend, for gathering Prometheus-format metrics. See the dedicated section.
• slf4j backends, for logging. See the dedicated section.

In addition, there are also backends for Scala.JS:

================================ ============================ ========================================= ============================
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
================================ ============================ ========================================= ============================

And a backend for scala-native:

================================ ============================ ========================================= ============================
Class                            Response wrapper             Supported stream type                     Supported websocket handlers
================================ ============================ ========================================= ============================
``CurlBackend``                  None (``Identity``)          n/a                                       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.