From b2b7ebaa82bc943d4761433f88d9187204ddd17e Mon Sep 17 00:00:00 2001 From: adamw Date: Tue, 13 Sep 2022 11:14:59 +0200 Subject: [PATCH] Release 3.8.0 --- README.md | 8 +- generated-docs/out/backends/akka.md | 4 +- generated-docs/out/backends/catseffect.md | 8 +- generated-docs/out/backends/finagle.md | 2 +- generated-docs/out/backends/fs2.md | 12 +-- generated-docs/out/backends/future.md | 8 +- generated-docs/out/backends/http4s.md | 4 +- .../out/backends/javascript/fetch.md | 12 +-- generated-docs/out/backends/monix.md | 8 +- generated-docs/out/backends/native/curl.md | 2 +- generated-docs/out/backends/scalaz.md | 4 +- generated-docs/out/backends/synchronous.md | 6 +- .../out/backends/wrappers/custom.md | 2 +- .../out/backends/wrappers/logging.md | 4 +- .../out/backends/wrappers/opentelemetry.md | 6 +- .../out/backends/wrappers/prometheus.md | 2 +- generated-docs/out/backends/zio.md | 12 +-- generated-docs/out/examples.md | 57 +++++++----- generated-docs/out/goals.md | 1 + generated-docs/out/index.md | 1 + generated-docs/out/json.md | 57 +++++++++--- generated-docs/out/openapi.md | 8 +- generated-docs/out/quickstart.md | 25 +++--- generated-docs/out/simple_sync.md | 87 +++++++++++++++++++ 24 files changed, 243 insertions(+), 97 deletions(-) create mode 100644 generated-docs/out/simple_sync.md diff --git a/README.md b/README.md index ce17bf50ef..8bd540e4fe 100755 --- a/README.md +++ b/README.md @@ -45,14 +45,14 @@ sttp (v2) documentation is available at [sttp.softwaremill.com/en/v2](http://stt sttp (v1) documentation is available at [sttp.softwaremill.com/en/v1](https://sttp.softwaremill.com/en/v1). -scaladoc is available at [https://www.javadoc.io](https://www.javadoc.io/doc/com.softwaremill.sttp.client3/core_2.12/3.7.6) +scaladoc is available at [https://www.javadoc.io](https://www.javadoc.io/doc/com.softwaremill.sttp.client3/core_2.12/3.8.0) ## Quickstart with Ammonite If you are an [Ammonite](http://ammonite.io) user, you can quickly start experimenting with sttp by copy-pasting the following: ```scala -import $ivy.`com.softwaremill.sttp.client3::core:3.7.6` +import $ivy.`com.softwaremill.sttp.client3::core:3.8.0` import sttp.client3.quick._ quickRequest.get(uri"http://httpbin.org/ip").send(backend) ``` @@ -64,7 +64,7 @@ This brings in the sttp API and a synchronous backend instance. Add the following dependency: ```scala -"com.softwaremill.sttp.client3" %% "core" % "3.7.6" +"com.softwaremill.sttp.client3" %% "core" % "3.8.0" ``` Then, import: @@ -102,7 +102,7 @@ The documentation is typechecked using [mdoc](https://scalameta.org/mdoc/). The When generating documentation, it's best to set the version to the current one, so that the generated doc files don't include modifications with the current snapshot version. -That is, in sbt run: `set version := "3.7.6"`, before running `mdoc` in `docs`. +That is, in sbt run: `set version := "3.8.0"`, before running `mdoc` in `docs`. ### Testing the Scala.JS backend diff --git a/generated-docs/out/backends/akka.md b/generated-docs/out/backends/akka.md index 673068ab3c..38a864556b 100644 --- a/generated-docs/out/backends/akka.md +++ b/generated-docs/out/backends/akka.md @@ -3,7 +3,7 @@ This backend is based on [akka-http](http://doc.akka.io/docs/akka-http/current/scala/http/). To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "akka-http-backend" % "3.7.6" +"com.softwaremill.sttp.client3" %% "akka-http-backend" % "3.8.0" ``` A fully **asynchronous** backend. Uses the `Future` effect to return responses. There are also [other `Future`-based backends](future.md), which don't depend on Akka. @@ -11,7 +11,7 @@ A fully **asynchronous** backend. Uses the `Future` effect to return responses. Note that you'll also need an explicit dependency on akka-streams, as akka-http doesn't depend on any specific akka-streams version. So you'll also need to add, for example: ``` -"com.typesafe.akka" %% "akka-stream" % "2.6.19" +"com.typesafe.akka" %% "akka-stream" % "2.6.20" ``` Next you'll need to add create the backend instance: diff --git a/generated-docs/out/backends/catseffect.md b/generated-docs/out/backends/catseffect.md index 209edfb730..3509a4e108 100644 --- a/generated-docs/out/backends/catseffect.md +++ b/generated-docs/out/backends/catseffect.md @@ -9,9 +9,9 @@ Note that all [fs2](fs2.md) backends also support any cats-effect effect, additi To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "async-http-client-backend-cats" % "3.7.6" // for cats-effect 3.x +"com.softwaremill.sttp.client3" %% "async-http-client-backend-cats" % "3.8.0" // for cats-effect 3.x // or -"com.softwaremill.sttp.client3" %% "async-http-client-backend-cats-ce2" % "3.7.6" // for cats-effect 2.x +"com.softwaremill.sttp.client3" %% "async-http-client-backend-cats-ce2" % "3.8.0" // for cats-effect 2.x ``` This backend depends on [async-http-client](https://github.com/AsyncHttpClient/async-http-client), uses [Netty](http://netty.io) behind the scenes. @@ -83,9 +83,9 @@ val backend = AsyncHttpClientCatsBackend.usingClient[IO](asyncHttpClient) To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "armeria-backend-cats" % "3.7.6" // for cats-effect 3.x +"com.softwaremill.sttp.client3" %% "armeria-backend-cats" % "3.8.0" // for cats-effect 3.x // or -"com.softwaremill.sttp.client3" %% "armeria-backend-cats-ce2" % "3.7.6" // for cats-effect 2.x +"com.softwaremill.sttp.client3" %% "armeria-backend-cats-ce2" % "3.8.0" // for cats-effect 2.x ``` create client: diff --git a/generated-docs/out/backends/finagle.md b/generated-docs/out/backends/finagle.md index 6517cb3c41..65af49dfaf 100644 --- a/generated-docs/out/backends/finagle.md +++ b/generated-docs/out/backends/finagle.md @@ -3,7 +3,7 @@ To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "finagle-backend" % "3.7.6" +"com.softwaremill.sttp.client3" %% "finagle-backend" % "3.8.0" ``` Next you'll need to add an implicit value: diff --git a/generated-docs/out/backends/fs2.md b/generated-docs/out/backends/fs2.md index 35187bd421..fb4aa9a14f 100644 --- a/generated-docs/out/backends/fs2.md +++ b/generated-docs/out/backends/fs2.md @@ -7,9 +7,9 @@ The [fs2](https://github.com/functional-streams-for-scala/fs2) backends are **as To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "fs2" % "3.7.6" // for cats-effect 3.x & fs2 3.x +"com.softwaremill.sttp.client3" %% "fs2" % "3.8.0" // for cats-effect 3.x & fs2 3.x // or -"com.softwaremill.sttp.client3" %% "fs2-ce2" % "3.7.6" // for cats-effect 2.x & fs2 2.x +"com.softwaremill.sttp.client3" %% "fs2-ce2" % "3.8.0" // for cats-effect 2.x & fs2 2.x ``` Obtain a cats-effect `Resource` which creates the backend, and closes the thread pool after the resource is no longer used: @@ -60,9 +60,9 @@ Host header override is supported in environments running Java 12 onwards, but i To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "async-http-client-backend-fs2" % "3.7.6" // for cats-effect 3.x & fs2 3.x +"com.softwaremill.sttp.client3" %% "async-http-client-backend-fs2" % "3.8.0" // for cats-effect 3.x & fs2 3.x // or -"com.softwaremill.sttp.client3" %% "async-http-client-backend-fs2-ce2" % "3.7.6" // for cats-effect 2.x & fs2 2.x +"com.softwaremill.sttp.client3" %% "async-http-client-backend-fs2-ce2" % "3.8.0" // for cats-effect 2.x & fs2 2.x ``` This backend depends on [async-http-client](https://github.com/AsyncHttpClient/async-http-client) and uses [Netty](http://netty.io) behind the scenes. @@ -141,9 +141,9 @@ val backend = AsyncHttpClientFs2Backend.usingClient[IO](asyncHttpClient, dispatc To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "armeria-backend-fs2" % "3.7.6" // for cats-effect 3.x & fs2 3.x +"com.softwaremill.sttp.client3" %% "armeria-backend-fs2" % "3.8.0" // for cats-effect 3.x & fs2 3.x // or -"com.softwaremill.sttp.client3" %% "armeria-backend-fs2" % "3.7.6" // for cats-effect 2.x & fs2 2.x +"com.softwaremill.sttp.client3" %% "armeria-backend-fs2" % "3.8.0" // for cats-effect 2.x & fs2 2.x ``` create client: diff --git a/generated-docs/out/backends/future.md b/generated-docs/out/backends/future.md index 30a265b257..be99381a18 100644 --- a/generated-docs/out/backends/future.md +++ b/generated-docs/out/backends/future.md @@ -21,7 +21,7 @@ Class Supported stream type To use, you don't need any extra dependencies, `core` is enough: ``` -"com.softwaremill.sttp.client3" %% "core" % "3.7.6" +"com.softwaremill.sttp.client3" %% "core" % "3.8.0" ``` You'll need the following imports: @@ -59,7 +59,7 @@ Host header override is supported in environments running Java 12 onwards, but i To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "async-http-client-backend-future" % "3.7.6" +"com.softwaremill.sttp.client3" %% "async-http-client-backend-future" % "3.8.0" ``` And some imports: @@ -110,7 +110,7 @@ val backend = AsyncHttpClientFutureBackend.usingClient(asyncHttpClient) To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "okhttp-backend" % "3.7.6" +"com.softwaremill.sttp.client3" %% "okhttp-backend" % "3.8.0" ``` and some imports: @@ -142,7 +142,7 @@ This backend depends on [OkHttp](http://square.github.io/okhttp/) and fully supp To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "armeria-backend" % "3.7.6" +"com.softwaremill.sttp.client3" %% "armeria-backend" % "3.8.0" ``` add imports: diff --git a/generated-docs/out/backends/http4s.md b/generated-docs/out/backends/http4s.md index 44b9d376c7..8adb77d155 100644 --- a/generated-docs/out/backends/http4s.md +++ b/generated-docs/out/backends/http4s.md @@ -3,9 +3,9 @@ This backend is based on [http4s](https://http4s.org) (client) and is **asynchronous**. To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "http4s-backend" % "3.7.6" // for cats-effect 3.x & http4s 1.0.0-Mx +"com.softwaremill.sttp.client3" %% "http4s-backend" % "3.8.0" // for cats-effect 3.x & http4s 1.0.0-Mx // or -"com.softwaremill.sttp.client3" %% "http4s-ce2-backend" % "3.7.6" // for cats-effect 2.x & http4s 0.21.x +"com.softwaremill.sttp.client3" %% "http4s-ce2-backend" % "3.8.0" // for cats-effect 2.x & http4s 0.21.x ``` The backend can be created in a couple of ways, e.g.: diff --git a/generated-docs/out/backends/javascript/fetch.md b/generated-docs/out/backends/javascript/fetch.md index 88ac22d822..432b82402c 100644 --- a/generated-docs/out/backends/javascript/fetch.md +++ b/generated-docs/out/backends/javascript/fetch.md @@ -7,7 +7,7 @@ A JavaScript backend with web socket support. Implemented using the [Fetch API]( This is the default backend, available in the main jar for JS. To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %%% "core" % "3.7.6" +"com.softwaremill.sttp.client3" %%% "core" % "3.8.0" ``` And create the backend instance: @@ -26,7 +26,7 @@ Note that `Fetch` does not pass cookies by default. If your request needs cookie To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %%% "monix" % "3.7.6" +"com.softwaremill.sttp.client3" %%% "monix" % "3.8.0" ``` And create the backend instance: @@ -40,7 +40,7 @@ val backend = FetchMonixBackend() To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %%% "zio" % "3.7.6" +"com.softwaremill.sttp.client3" %%% "zio" % "3.8.0" ``` And create the backend instance: @@ -55,13 +55,13 @@ Any effect implementing the cats-effect `Concurrent` typeclass can be used. To u your project: ``` -"com.softwaremill.sttp.client3" %%% "cats" % "3.7.6" +"com.softwaremill.sttp.client3" %%% "cats" % "3.8.0" ``` If you are on Cats Effect 2 (CE2) you will need to add the CE2 specific dependency instead: ``` -"com.softwaremill.sttp.client3" %%% "catsce2 % "3.7.6" +"com.softwaremill.sttp.client3" %%% "catsce2 % "3.8.0" ``` And create the backend instance: @@ -129,7 +129,7 @@ Streaming support is provided via `FetchMonixBackend`. Note that streaming suppo To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %%% "monix" % "3.7.6" +"com.softwaremill.sttp.client3" %%% "monix" % "3.8.0" ``` An example of streaming a response: diff --git a/generated-docs/out/backends/monix.md b/generated-docs/out/backends/monix.md index d2018c09c7..6168b9f6e3 100644 --- a/generated-docs/out/backends/monix.md +++ b/generated-docs/out/backends/monix.md @@ -7,7 +7,7 @@ There are several backend implementations which are `monix.eval.Task`-based. The To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "monix" % "3.7.6" +"com.softwaremill.sttp.client3" %% "monix" % "3.8.0" ``` Create the backend using: @@ -39,7 +39,7 @@ Host header override is supported in environments running Java 12 onwards, but i To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "async-http-client-backend-monix" % "3.7.6" +"com.softwaremill.sttp.client3" %% "async-http-client-backend-monix" % "3.8.0" ``` This backend depends on [async-http-client](https://github.com/AsyncHttpClient/async-http-client), uses [Netty](http://netty.io) behind the scenes. @@ -82,7 +82,7 @@ val backend = AsyncHttpClientMonixBackend.usingClient(asyncHttpClient) To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "okhttp-backend-monix" % "3.7.6" +"com.softwaremill.sttp.client3" %% "okhttp-backend-monix" % "3.8.0" ``` Create the backend using: @@ -108,7 +108,7 @@ This backend depends on [OkHttp](http://square.github.io/okhttp/) and fully supp To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "armeria-backend-monix" % "3.7.6" +"com.softwaremill.sttp.client3" %% "armeria-backend-monix" % "3.8.0" ``` add imports: diff --git a/generated-docs/out/backends/native/curl.md b/generated-docs/out/backends/native/curl.md index 637f38e9fe..a4b86bd137 100644 --- a/generated-docs/out/backends/native/curl.md +++ b/generated-docs/out/backends/native/curl.md @@ -5,7 +5,7 @@ A Scala Native backend implemented using [Curl](https://github.com/curl/curl/blo To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %%% "core" % "3.7.6" +"com.softwaremill.sttp.client3" %%% "core" % "3.8.0" ``` and initialize one of the backends: diff --git a/generated-docs/out/backends/scalaz.md b/generated-docs/out/backends/scalaz.md index 8c6a7219e8..a11d61edc4 100644 --- a/generated-docs/out/backends/scalaz.md +++ b/generated-docs/out/backends/scalaz.md @@ -7,7 +7,7 @@ The [Scalaz](https://github.com/scalaz/scalaz) backend is **asynchronous**. Send To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "async-http-client-backend-scalaz" % "3.7.6" +"com.softwaremill.sttp.client3" %% "async-http-client-backend-scalaz" % "3.8.0" ``` This backend depends on [async-http-client](https://github.com/AsyncHttpClient/async-http-client) and uses [Netty](http://netty.io) behind the scenes. @@ -45,7 +45,7 @@ val backend = AsyncHttpClientScalazBackend.usingClient(asyncHttpClient) To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "armeria-backend-scalaz" % "3.7.6" +"com.softwaremill.sttp.client3" %% "armeria-backend-scalaz" % "3.8.0" ``` add imports: diff --git a/generated-docs/out/backends/synchronous.md b/generated-docs/out/backends/synchronous.md index 84496a1ec6..762cd68dce 100644 --- a/generated-docs/out/backends/synchronous.md +++ b/generated-docs/out/backends/synchronous.md @@ -7,7 +7,7 @@ There are several synchronous backend implementations. Sending a request using t The default **synchronous** backend. To use, you don't need any extra dependencies, `core` is enough: ``` -"com.softwaremill.sttp.client3" %% "core" % "3.7.6" +"com.softwaremill.sttp.client3" %% "core" % "3.8.0" ``` Create the backend using: @@ -40,7 +40,7 @@ Host header override is supported in environments running Java 12 onwards, but i To use, you don't need any extra dependencies, `core` is enough: ``` -"com.softwaremill.sttp.client3" %% "core" % "3.7.6" +"com.softwaremill.sttp.client3" %% "core" % "3.8.0" ``` Create the backend using: @@ -62,7 +62,7 @@ This backend supports host header override, but it has to be enabled by system p To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "okhttp-backend" % "3.7.6" +"com.softwaremill.sttp.client3" %% "okhttp-backend" % "3.8.0" ``` Create the backend using: diff --git a/generated-docs/out/backends/wrappers/custom.md b/generated-docs/out/backends/wrappers/custom.md index 4f10a7d7b4..d542684eda 100644 --- a/generated-docs/out/backends/wrappers/custom.md +++ b/generated-docs/out/backends/wrappers/custom.md @@ -238,7 +238,7 @@ object RateLimitingSttpBackend { Implementing a new backend is made easy as the tests are published in the `core` jar file under the `tests` classifier. Simply add the follow dependencies to your `build.sbt`: ``` -"com.softwaremill.sttp.client3" %% "core" % "3.7.6" % Test classifier "tests" +"com.softwaremill.sttp.client3" %% "core" % "3.8.0" % Test classifier "tests" ``` Implement your backend and extend the `HttpTest` class: diff --git a/generated-docs/out/backends/wrappers/logging.md b/generated-docs/out/backends/wrappers/logging.md index 419e6d8697..711d1b35c6 100644 --- a/generated-docs/out/backends/wrappers/logging.md +++ b/generated-docs/out/backends/wrappers/logging.md @@ -28,7 +28,7 @@ Log levels can be configured when creating the `LoggingBackend`, or specified in To use the [slf4j](http://www.slf4j.org) logging backend wrapper, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "slf4j-backend" % "3.7.6" +"com.softwaremill.sttp.client3" %% "slf4j-backend" % "3.8.0" ``` There are three backend wrappers available, which log request & response information using a slf4j `Logger`. To see the logs, you'll need to use an slf4j-compatible logger implementation, e.g. [logback](http://logback.qos.ch), or use a binding, e.g. [log4j-slf4j](https://logging.apache.org/log4j/2.0/log4j-slf4j-impl/index.html). @@ -50,5 +50,5 @@ To create a customised logging backend, see the section on [custom backends](cus To use the [scribe](https://github.com/outr/scribe) logging backend wrapper, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "scribe-backend" % "3.7.6" +"com.softwaremill.sttp.client3" %% "scribe-backend" % "3.8.0" ``` \ No newline at end of file diff --git a/generated-docs/out/backends/wrappers/opentelemetry.md b/generated-docs/out/backends/wrappers/opentelemetry.md index a94b3f0902..de48788386 100644 --- a/generated-docs/out/backends/wrappers/opentelemetry.md +++ b/generated-docs/out/backends/wrappers/opentelemetry.md @@ -12,7 +12,7 @@ The backend depends only on [opentelemetry-api](https://github.com/open-telemetr following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "opentelemetry-metrics-backend" % "3.7.6" +"com.softwaremill.sttp.client3" %% "opentelemetry-metrics-backend" % "3.8.0" ``` Then an instance can be obtained as follows: @@ -53,8 +53,8 @@ OpenTelemetryMetricsBackend( To use, add the following dependency to your project (the `zio-*` modules depend on ZIO 2.x; for ZIO 1.x support, use `zio1-*`): ``` -"com.softwaremill.sttp.client3" %% "opentelemetry-tracing-zio-backend" % "3.7.6" // for ZIO 2.x -"com.softwaremill.sttp.client3" %% "opentelemetry-tracing-zio1-backend" % "3.7.6" // for ZIO 1.x +"com.softwaremill.sttp.client3" %% "opentelemetry-tracing-zio-backend" % "3.8.0" // for ZIO 2.x +"com.softwaremill.sttp.client3" %% "opentelemetry-tracing-zio1-backend" % "3.8.0" // for ZIO 1.x ``` This backend depends on [zio-opentelemetry](https://github.com/zio/zio-telemetry). diff --git a/generated-docs/out/backends/wrappers/prometheus.md b/generated-docs/out/backends/wrappers/prometheus.md index 873b7ed079..ab4d01db3b 100644 --- a/generated-docs/out/backends/wrappers/prometheus.md +++ b/generated-docs/out/backends/wrappers/prometheus.md @@ -3,7 +3,7 @@ To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "prometheus-backend" % "3.7.6" +"com.softwaremill.sttp.client3" %% "prometheus-backend" % "3.8.0" ``` and some imports: diff --git a/generated-docs/out/backends/zio.md b/generated-docs/out/backends/zio.md index d839c6eced..ab09285de1 100644 --- a/generated-docs/out/backends/zio.md +++ b/generated-docs/out/backends/zio.md @@ -9,8 +9,8 @@ The `*-zio` modules depend on ZIO 2.x. For ZIO 1.x support, use modules with the To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "zio" % "3.7.6" // for ZIO 2.x -"com.softwaremill.sttp.client3" %% "zio1" % "3.7.6" // for ZIO 1.x +"com.softwaremill.sttp.client3" %% "zio" % "3.8.0" // for ZIO 2.x +"com.softwaremill.sttp.client3" %% "zio1" % "3.8.0" // for ZIO 1.x ``` Create the backend using: @@ -42,8 +42,8 @@ Host header override is supported in environments running Java 12 onwards, but i To use, add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "async-http-client-backend-zio" % "3.7.6" // for ZIO 2.x -"com.softwaremill.sttp.client3" %% "async-http-client-backend-zio1" % "3.7.6" // for ZIO 1.x +"com.softwaremill.sttp.client3" %% "async-http-client-backend-zio" % "3.8.0" // for ZIO 2.x +"com.softwaremill.sttp.client3" %% "async-http-client-backend-zio1" % "3.8.0" // for ZIO 1.x ``` This backend depends on [async-http-client](https://github.com/AsyncHttpClient/async-http-client), uses [Netty](http://netty.io) behind the scenes. This backend works with all Scala versions. A Scala 3 build is available as well. @@ -84,8 +84,8 @@ val backend = AsyncHttpClientZioBackend.usingClient(runtime, asyncHttpClient) To use, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "armeria-backend-zio" % "3.7.6" // for ZIO 2.x -"com.softwaremill.sttp.client3" %% "armeria-backend-zio1" % "3.7.6" // for ZIO 1.x +"com.softwaremill.sttp.client3" %% "armeria-backend-zio" % "3.8.0" // for ZIO 2.x +"com.softwaremill.sttp.client3" %% "armeria-backend-zio1" % "3.8.0" // for ZIO 1.x ``` add imports: diff --git a/generated-docs/out/examples.md b/generated-docs/out/examples.md index 354f3cb23f..752eec9916 100644 --- a/generated-docs/out/examples.md +++ b/generated-docs/out/examples.md @@ -2,12 +2,27 @@ All of the examples are available [in the sources](https://github.com/softwaremill/sttp/blob/master/examples/src/main/scala/sttp/client3/examples) in runnable form. +## Use the simple synchronous client + +Required dependencies: + +```scala +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "core" % "3.8.0") +``` + +Example code: + +```eval_rst +.. literalinclude:: ../../examples/src/main/scala/sttp/client3/examples/SimpleClientGetAndPost.scala + :language: scala +``` + ## POST a form using the synchronous backend Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "core" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "core" % "3.8.0") ``` Example code: @@ -23,8 +38,8 @@ Required dependencies: ```scala libraryDependencies ++= List( - "com.softwaremill.sttp.client3" %% "akka-http-backend" % "3.7.6", - "com.softwaremill.sttp.client3" %% "json4s" % "3.7.6", + "com.softwaremill.sttp.client3" %% "akka-http-backend" % "3.8.0", + "com.softwaremill.sttp.client3" %% "json4s" % "3.8.0", "org.json4s" %% "json4s-native" % "3.6.0" ) ``` @@ -42,8 +57,8 @@ Required dependencies: ```scala libraryDependencies ++= List( - "com.softwaremill.sttp.client3" %% "async-http-client-backend-zio" % "3.7.6", - "com.softwaremill.sttp.client3" %% "circe" % "3.7.6", + "com.softwaremill.sttp.client3" %% "async-http-client-backend-zio" % "3.8.0", + "com.softwaremill.sttp.client3" %% "circe" % "3.8.0", "io.circe" %% "circe-generic" % "0.14.1" ) ``` @@ -61,8 +76,8 @@ Required dependencies: ```scala libraryDependencies ++= List( - "com.softwaremill.sttp.client3" %% "async-http-client-backend-monix" % "3.7.6", - "com.softwaremill.sttp.client3" %% "circe" % "3.7.6", + "com.softwaremill.sttp.client3" %% "async-http-client-backend-monix" % "3.8.0", + "com.softwaremill.sttp.client3" %% "circe" % "3.8.0", "io.circe" %% "circe-generic" % "0.14.1" ) ``` @@ -80,8 +95,8 @@ Required dependencies: ```scala libraryDependencies ++= List( - "com.softwaremill.sttp.client3" %% "slf4j-backend" % "3.7.6", - "com.softwaremill.sttp.client3" %% "circe" % "3.7.6", + "com.softwaremill.sttp.client3" %% "slf4j-backend" % "3.8.0", + "com.softwaremill.sttp.client3" %% "circe" % "3.8.0", "io.circe" %% "circe-generic" % "0.14.1" ) ``` @@ -99,8 +114,8 @@ Required dependencies: ```scala libraryDependencies ++= List( - "com.softwaremill.sttp.client3" %% "async-http-client-backend-monix" % "3.7.6", - "com.softwaremill.sttp.client3" %% "circe" % "3.7.6", + "com.softwaremill.sttp.client3" %% "async-http-client-backend-monix" % "3.8.0", + "com.softwaremill.sttp.client3" %% "circe" % "3.8.0", "io.circe" %% "circe-generic" % "0.14.1" ) ``` @@ -117,7 +132,7 @@ Example code: Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "core" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "core" % "3.8.0") ``` Example code: @@ -132,7 +147,7 @@ Example code: Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-zio" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-zio" % "3.8.0") ``` Example code: @@ -147,7 +162,7 @@ Example code: Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-fs2" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-fs2" % "3.8.0") ``` Example code: @@ -162,7 +177,7 @@ Example code: Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-monix" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-monix" % "3.8.0") ``` Example code: @@ -177,7 +192,7 @@ Example code: Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "akka-http-backend" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "akka-http-backend" % "3.8.0") ``` Example code: @@ -192,7 +207,7 @@ Example code: Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-monix" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-monix" % "3.8.0") ``` Example code: @@ -207,7 +222,7 @@ Example code: Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-fs2" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-fs2" % "3.8.0") ``` Example code: @@ -222,7 +237,7 @@ Example code: Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-zio" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-zio" % "3.8.0") ``` Example code: @@ -237,7 +252,7 @@ Example code: Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-zio" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "async-http-client-backend-zio" % "3.8.0") ``` Example code: @@ -252,7 +267,7 @@ Example code: Required dependencies: ```scala -libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "core" % "3.7.6") +libraryDependencies ++= List("com.softwaremill.sttp.client3" %% "core" % "3.8.0") ``` Example code: diff --git a/generated-docs/out/goals.md b/generated-docs/out/goals.md index 7d8f193b68..2c056838dd 100644 --- a/generated-docs/out/goals.md +++ b/generated-docs/out/goals.md @@ -14,6 +14,7 @@ See also the blog posts: * [sttp2: an overview of proposed changes](https://blog.softwaremill.com/sttp2-an-overview-of-proposed-changes-8de23c94684f) * [Migrating to sttp client 2.x and tapir 0.12.x](https://blog.softwaremill.com/migrating-to-sttp-client-2-x-and-tapir-0-12-x-7956e6c79c52) * [What’s coming up in sttp client 3?](https://blog.softwaremill.com/whats-coming-up-in-sttp-client-3-30d01ab42d1b) +* [sttp client 3 is here!](https://blog.softwaremill.com/sttp-client-3-is-here-bb9ebe925931) ## Non-goals of the project diff --git a/generated-docs/out/index.md b/generated-docs/out/index.md index bd043c86c9..0c800947a8 100644 --- a/generated-docs/out/index.md +++ b/generated-docs/out/index.md @@ -70,6 +70,7 @@ Development and maintenance of sttp client is sponsored by [SoftwareMill](https: :caption: Getting started quickstart + simple_sync how goals community diff --git a/generated-docs/out/json.md b/generated-docs/out/json.md index 489e3c8a69..4a4a93b01f 100644 --- a/generated-docs/out/json.md +++ b/generated-docs/out/json.md @@ -34,7 +34,7 @@ case class ResponsePayload(data: String) JSON encoding of bodies and decoding of responses can be handled using [Circe](https://circe.github.io/circe/) by the `circe` module. To use add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "circe" % "3.7.6" +"com.softwaremill.sttp.client3" %% "circe" % "3.8.0" ``` This module adds a body serialized, so that json payloads can be sent as request bodies. To send a payload of type `T` as json, a `io.circe.Encoder[T]` implicit value must be available in scope. @@ -66,7 +66,7 @@ Arbitrary JSON structures can be traversed by parsing the result as `io.circe.Js To encode and decode json using json4s, add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "json4s" % "3.7.6" +"com.softwaremill.sttp.client3" %% "json4s" % "3.8.0" "org.json4s" %% "json4s-native" % "3.6.0" ``` @@ -100,7 +100,7 @@ val response: Identity[Response[Either[ResponseException[String, Exception], Res To encode and decode JSON using [spray-json](https://github.com/spray/spray-json), add the following dependency to your project: ``` -"com.softwaremill.sttp.client3" %% "spray-json" % "3.7.6" +"com.softwaremill.sttp.client3" %% "spray-json" % "3.8.0" ``` Using this module it is possible to set request bodies and read response bodies as your custom types, using the implicitly available instances of `spray.json.JsonWriter` / `spray.json.JsonReader` or `spray.json.JsonFormat`. @@ -132,7 +132,7 @@ val response: Identity[Response[Either[ResponseException[String, Exception], Res To encode and decode JSON using [play-json](https://www.playframework.com), add the following dependency to your project: ```scala -"com.softwaremill.sttp.client3" %% "play-json" % "3.7.6" +"com.softwaremill.sttp.client3" %% "play-json" % "3.8.0" ``` To use, add an import: `import sttp.client3.playJson._`. @@ -144,13 +144,13 @@ To encode and decode JSON using the high-performance [zio-json](https://zio.gith The `zio-json` module depends on ZIO 2.x. For ZIO 1.x support, use `zio1-json`. ```scala -"com.softwaremill.sttp.client3" %% "zio-json" % "3.7.6" // for ZIO 2.x -"com.softwaremill.sttp.client3" %% "zio1-json" % "3.7.6" // for ZIO 1.x +"com.softwaremill.sttp.client3" %% "zio-json" % "3.8.0" // for ZIO 2.x +"com.softwaremill.sttp.client3" %% "zio1-json" % "3.8.0" // for ZIO 1.x ``` or for ScalaJS (cross build) projects: ```scala -"com.softwaremill.sttp.client3" %%% "zio-json" % "3.7.6" // for ZIO 2.x -"com.softwaremill.sttp.client3" %%% "zio1-json" % "3.7.6" // for ZIO 1.x +"com.softwaremill.sttp.client3" %%% "zio-json" % "3.8.0" // for ZIO 2.x +"com.softwaremill.sttp.client3" %%% "zio1-json" % "3.8.0" // for ZIO 1.x ``` To use, add an import: `import sttp.client3.ziojson._` (or extend `SttpZioJsonApi`), define an implicit `JsonCodec`, or `JsonDecoder`/`JsonEncoder` for your datatype. @@ -182,13 +182,13 @@ basicRequest To encode and decode JSON using the [high(est)-performant](https://plokhotnyuk.github.io/jsoniter-scala/) [jsoniter-scala](https://github.com/plokhotnyuk/jsoniter-scala) library, one add the following dependency to your project. ```scala -"com.softwaremill.sttp.client3" %% "jsoniter-json" % "3.7.6" +"com.softwaremill.sttp.client3" %% "jsoniter-json" % "3.8.0" ``` or for ScalaJS (cross build) projects: ```scala -"com.softwaremill.sttp.client3" %%% "jsoniter-json" % "3.7.6" +"com.softwaremill.sttp.client3" %%% "jsoniter-json" % "3.8.0" ``` To use, add an import: `import sttp.client3.jsoniter._` (or extend `SttpJsonIterJsonApi`), define an implicit `JsonCodec`, or `JsonDecoder`/`JsonEncoder` for your datatype. @@ -209,6 +209,43 @@ implicit val payloadJsonCodec: JsonValueCodec[RequestPayload] = JsonCodecMaker.m implicit val jsonEitherDecoder: JsonValueCodec[ResponsePayload] = JsonCodecMaker.make val requestPayload = RequestPayload("some data") +val response: Identity[Response[Either[ResponseException[String, Exception], ResponsePayload]]] = +basicRequest + .post(uri"...") + .body(requestPayload) + .response(asJson[ResponsePayload]) + .send(backend) +``` + +## uPickle + +To encode and decode JSON using the [uPickle](https://github.com/com-lihaoyi/upickle) library, add the following dependency to your project: + +```scala +"com.softwaremill.sttp.client3" %% "upickle" % "3.8.0" +``` + +or for ScalaJS (cross build) projects: + +```scala +"com.softwaremill.sttp.client3" %%% "upickle" % "3.8.0" +``` + +To use, add an import: `import sttp.client3.upicklejson._` (or extend `SttpUpickleApi`) and define an implicit `ReadWriter` (or separately `Reader` and `Writer`) for your datatype. +Usage example: + +```scala +import sttp.client3._ +import sttp.client3.upicklejson._ +import upickle.default._ + +val backend: SttpBackend[Identity, Any] = HttpClientSyncBackend() + +implicit val requestPayloadRW: ReadWriter[RequestPayload] = macroRW[RequestPayload] +implicit val responsePayloadRW: ReadWriter[ResponsePayload] = macroRW[ResponsePayload] + +val requestPayload = RequestPayload("some data") + val response: Identity[Response[Either[ResponseException[String, Exception], ResponsePayload]]] = basicRequest .post(uri"...") diff --git a/generated-docs/out/openapi.md b/generated-docs/out/openapi.md index 4c546d6e9c..717af1c037 100644 --- a/generated-docs/out/openapi.md +++ b/generated-docs/out/openapi.md @@ -45,8 +45,8 @@ lazy val petstoreApi: Project = project openApiGeneratorName := "scala-sttp", openApiOutputDir := baseDirectory.value.name, libraryDependencies ++= Seq( - "com.softwaremill.sttp.client3" %% "core" % "3.7.6", - "com.softwaremill.sttp.client3" %% "json4s" % "3.7.6", + "com.softwaremill.sttp.client3" %% "core" % "3.8.0", + "com.softwaremill.sttp.client3" %% "json4s" % "3.8.0", "org.json4s" %% "json4s-jackson" % "3.6.8" ) ) @@ -96,8 +96,8 @@ lazy val petstoreApi: Project = project openApiOutputDir := baseDirectory.value.name, openApiIgnoreFileOverride := s"${baseDirectory.in(ThisBuild).value.getPath}/openapi-ignore-file", libraryDependencies ++= Seq( - "com.softwaremill.sttp.client3" %% "core" % "3.7.6", - "com.softwaremill.sttp.client3" %% "json4s" % "3.7.6", + "com.softwaremill.sttp.client3" %% "core" % "3.8.0", + "com.softwaremill.sttp.client3" %% "json4s" % "3.8.0", "org.json4s" %% "json4s-jackson" % "3.6.8" ), (compile in Compile) := ((compile in Compile) dependsOn openApiGenerate).value, diff --git a/generated-docs/out/quickstart.md b/generated-docs/out/quickstart.md index 10a26a4dd8..1f7da79ce8 100644 --- a/generated-docs/out/quickstart.md +++ b/generated-docs/out/quickstart.md @@ -1,37 +1,42 @@ # Quickstart -The core sttp client API comes in a single jar, with a transitive dependency on [sttp model](https://github.com/softwaremill/sttp-model). This also includes a default, [synchronous](backends/synchronous.md) backend, which is based on Java's `HttpClient`. +The core sttp client API comes in a single jar, with a transitive dependency on [sttp model](https://github.com/softwaremill/sttp-model). This also includes a default [synchronous simple client](simple_sync.md) and [synchronous](backends/synchronous.md) and [`Future`-based] backends, based on Java's `HttpClient`. -To integrate with other parts of your application, you'll often need to use an alternate backend (but what's important is that the API remains the same!). See the section on [backends](backends/summary.md) for a short guide on which backend to choose, and a list of all implementations. +To integrate with other parts of your application and various effect systems, you'll often need to use an alternate backend (but what's important is that the API remains the same!). See the section on [backends](backends/summary.md) for a short guide on which backend to choose, and a list of all implementations. + +`sttp client` is available for Scala 2.11, 2.12 and 2.13, as well as for Scala 3 and requires Java 11 or higher. + +`sttp client` is also available for Scala.js 1.0 and Scala Native. Note that not all modules are compatible with these +platforms, and that each has its own dedicated set of backends. ## Using sbt The basic dependency which provides the API, together with a synchronous and `Future`-based backends, is: ```scala -"com.softwaremill.sttp.client3" %% "core" % "3.7.6" +"com.softwaremill.sttp.client3" %% "core" % "3.8.0" ``` -`sttp client` is available for Scala 2.11, 2.12 and 2.13, as well as for Scala 3 and requires Java 11. +## Simple synchronous client -`sttp client` is also available for Scala.js 1.0. Note that not all modules are compatible and there are no backends that can be used on both. The last version compatible with Scala.js 0.6 was 2.2.1. Scala Native is supported as well. +If you'd like to send some requests synchronously, take a look at the [simple synchronous client](simple_sync.md). ## Using Ammonite If you are an [Ammonite](https://ammonite.io) user, you can quickly start experimenting with sttp by copy-pasting the following: ```scala -import $ivy.`com.softwaremill.sttp.client3::core:3.7.6` +import $ivy.`com.softwaremill.sttp.client3::core:3.8.0` import sttp.client3.quick._ -quickRequest.get(uri"http://httpbin.org/ip").send(backend) +simpleSttpClient.send(quickRequest.get(uri"http://httpbin.org/ip")) ``` Importing the `quick` object has the same effect as importing `sttp.client3._`, plus defining a synchronous backend (`val backend = HttpClientSyncBackend()`), so that sttp can be used right away. -If the default `HttpURLConnectionBackend` for some reason is insufficient, you can also use one based on OkHttp or HttpClient: +If the default backend is for some reason insufficient, you can also use one based on OkHttp: ```scala -import $ivy.`com.softwaremill.sttp.client3::okhttp-backend:3.7.6` +import $ivy.`com.softwaremill.sttp.client3::okhttp-backend:3.8.0` import sttp.client3.okhttp.quick._ quickRequest.get(uri"http://httpbin.org/ip").send(backend) ``` @@ -59,4 +64,4 @@ val response = basicRequest println(response.body) ``` -Next, read on about the [how sttp client works](how.md) or see some [examples](examples.md). +Next, read on [how sttp client works](how.md) or see some [examples](examples.md). diff --git a/generated-docs/out/simple_sync.md b/generated-docs/out/simple_sync.md new file mode 100644 index 0000000000..a49d57bbd1 --- /dev/null +++ b/generated-docs/out/simple_sync.md @@ -0,0 +1,87 @@ +# Simple synchronous client + +The core module of sttp client includes a simple, synchronous client, which can be used to send requests without +the need to choose or explicitly create a backend. + +A simple request can be sent as follows: + +```scala +import sttp.client3.{SimpleHttpClient, UriContext, basicRequest} + +val client = SimpleHttpClient() +val response = client.send(basicRequest.get(uri"https://httpbin.org/get")) +println(response.body) +``` + +Creating a client allocates resources (such as selector threads / connection pools), so when it's no longer needed, it +should be closed using `.close()`. Typically, you should have one client instance for your entire application. + +## Serialising and parsing JSON + +To serialize a custom type to a JSON body, or to deserialize the response body that is in the JSON format, you'll need +to add an integration with a JSON library. See [json](json.md) for a list of available libraries. + +As an example, to integrate with the [uPickle](https://github.com/com-lihaoyi/upickle) library, add the following +dependency: + +```scala +"com.softwaremill.sttp.client3" %% "upickle" % "3.8.0" +``` + +Your code might then look as follows: + +```scala +import sttp.client3.{SimpleHttpClient, UriContext, basicRequest} +import sttp.client3.upicklejson._ +import upickle.default._ + +val client = SimpleHttpClient() + +case class MyRequest(field1: String, field2: Int) +// selected fields from the JSON that is being returned by httpbin +case class HttpBinResponse(origin: String, headers: Map[String, String]) + +implicit val myRequestRW: ReadWriter[MyRequest] = macroRW[MyRequest] +implicit val responseRW: ReadWriter[HttpBinResponse] = macroRW[HttpBinResponse] + +val request = basicRequest + .post(uri"https://httpbin.org/post") + .body(MyRequest("test", 42)) + .response(asJson[HttpBinResponse]) +val response = client.send(request) + +response.body match { + case Left(e) => println(s"Got response exception:\n$e") + case Right(r) => println(s"Origin's ip: ${r.origin}, header count: ${r.headers.size}") +} +``` + +## Adding logging + +Logging can be added using the [logging backend wrapper](backends/wrappers/logging.md). For example, if you'd like to +use slf4j, you'll need the following dependency: + +``` +"com.softwaremill.sttp.client3" %% "slf4j-backend" % "3.8.0" +``` + +Then, you'll need to configure your client: + +```scala +import sttp.client3.{SimpleHttpClient, UriContext, basicRequest} +import sttp.client3.logging.slf4j.Slf4jLoggingBackend + +val client = SimpleHttpClient().wrapBackend(Slf4jLoggingBackend(_)) +``` + +## Relationship with backends + +The `SimpleHttpClient` serves as a simple starting point for sending requests in a synchronous way. For more advanced +use-cases, you should use an [sttp backend](backends/summary.md) directly. For example, if you'd like to send requests +asynchronously, getting a `Future` as the result. Or, if you manage side effects using an `IO` or `Task`. + +In fact, an instance of `SimpleHttpClient` is a thin wrapper on top of a backend. + +## Next steps + +Read on [how sttp client works](how.md) or see some more [examples](examples.md). \ No newline at end of file