sttp client 3 is here!

After a long series of RC releases, many planned and unplanned changes, the 3.0.0 release is here. Let’s take a brief look at what’s new & changed.

But what is sttp client?

It’s the Scala HTTP client that you always wanted! More elaborately, quoting the documentation:

sttp client is an open-source library which provides a clean, programmer-friendly API to describe HTTP requests and how to handle responses. Requests are sent using one of the backends, which wrap other Scala or Java HTTP client implementations. The backends can integrate with a variety of Scala stacks, providing both synchronous and asynchronous, procedural and functional interfaces.

Backend implementations include ones based on akka-http, async-http-client, http4s, OkHttp, and HTTP clients which ship with Java. They integrate with Akka, Monix, fs2, cats-effect, scalaz and ZIO. Supported Scala versions include 2.11, 2.12, 2.13 and 3.

What’s new?

The focus in sttp client 3 is to make the API simpler, safer and more developer-friendly. Here’s a quick list of the most important changes:

• simpler SttpBackend trait — 2 (instead of 3) type parameters and 3 methods (instead of 4). To write a custom backend wrapper (implementing custom logging or tracing, for example), you’ll typically need to implement a single method: send[T](request: Request[T, R]): F[Response[T]].
• web socket responses are defined in the same way as others. Just as you have asString, asJson or asStream to describe how the response should be handled, web socket responses are specified using asWebSocket and asWebSocketStream.
• safer stream handling. By default, you need to provide an (effectful) function, which will consume the streaming respomnse body, e.g. asStream(f: Source[ByteString, Any] => F[T]) in case of akka-streams. This will ensure that the body is always either read fully or discarded.
• server-sent events (SSE) parsing in all backends which support non-blocking streams. Simply chain the included parser (for Monix/ZIO/fs2/akka streams) with a streaming body.
• more flexibility in error handling: when receiving JSON with asJson, as part of the response, you now get the library-specific error that can occur during parsing. Or, you can specify separate decoders for 2xx and 4xx/5xx responses using asJsonEither. Finally, you can represent any failed requests as failed effects (due to connection or response parsing exceptions, and 4xx/5xx responses) using asJson.getRight.
• extended SttpBackendStub (for testing) to support web sockets and improve stream handling. Recording requests is also possible. The request body can be more easily matched on using request.forceBodyAsString.
• rewritten LoggingBackend which offers much greater flexibility in defining what should be included in the log messages, and what should be the log levels.
• relative URIs support, along with ResolveRelativeUrisBackend. This makes sttp client more usable in a JS browser environment. Also, the sttp model is improved in many places, adding for example cache directive parsing.

Some of these functionalities are described in more detail in the “What’s coming up in sttp client 3” blog, along with code snippets. The documentation also includes a number of examples, which hopefully will provide a good template to find solutions to everyday problems. Finally, the release notes include a short migration guide, which will help you upgrade from previous versions.

Try it out

If you’d like to try sttp client 3, add the following dependency:

"com.softwaremill.sttp.client3" %% "core" % "3.0.0"

Then, add import sttp.client3._, take a look at basicRequest, and see where your IDEs auto-complete gets you! By calling methods on the request description, you can customise it as required by your use case, and then send it using of the available backends.

Quite importantly, sttp client 3 uses a new organization and package, hence it can be used alongside sttp client 2 (or even sttp client 1).

This release was possible thanks to a number of contributors, both providing PRs with bug fixes, new functionalities, but also bug reports and testing of the RC versions. Thank you!

If you’d like to participate in sttp projects, don’t hesitate to write on gitter or create an issue.