More docs

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.
+