sttp: the Scala HTTP client you always wanted!
This is the development version of the upcoming sttp client 4. For the current stable version, see sttp 3 on GitHub and its documentation.
Welcome!
sttp client is an open-source HTTP client for Scala, supporting various approaches to writing Scala code: synchronous (direct-style), Future
-based, and using functional effect systems (cats-effect, ZIO, Monix, Kyo, scalaz).
The library is available for Scala 2.12, 2.13 and 3. Supported platforms are the JVM (Java 11+), Scala.JS and Scala Native.
Here’s a quick example of sttp client in action, runnable using scala-cli:
//> using dep com.softwaremill.sttp.client4::core:4.0.0-M25
import sttp.client4.quick.*
@main def run(): Unit =
println(quickRequest.get(uri"http://httpbin.org/ip").send())
sttp client addresses common HTTP client use cases, such as interacting with JSON APIs (with automatic serialization of request bodies and deserialization of response bodies), uploading and downloading files, submitting form data, handling multipart requests, and working with WebSockets.
The driving principle of sttp client’s design is to provide a clean, programmer-friendly API to describe HTTP requests, along with response handling. This ensures that resources, such as HTTP connections, are used safely, also in the presence of errors.
sttp client integrates with a number of lower-level Scala and Java HTTP client implementations through backends (using Java’s HttpClient
, Akka HTTP, Pekko HTTP, http4s, OkHttp, Armeria), offering a wide range of choices when it comes to protocol support, connectivity settings and programming stack compatibility.
Additionally, sttp client seamlessly integrates with popular libraries for JSON handling (e.g., circe, uPickle, jsoniter, json4s, play-json, ZIO Json), logging, metrics, and tracing (e.g., slf4j, scribe, OpenTelemetry, Prometheus). It also supports streaming libraries (e.g., fs2, ZIO Streams, Akka Streams, Pekko Streams) and provides tools for testing HTTP interactions.
Some more features: URI interpolation, a self-managed backend, and type-safe HTTP error/success representation, are demonstrated by the below example:
//> using dep com.softwaremill.sttp.client4::core:4.0.0-M25
import sttp.client4.*
@main def sttpDemo(): Unit =
val sort: Option[String] = None
val query = "http language:scala"
// the `query` parameter is automatically url-encoded
// `sort` is removed, as the value is not defined
val request = basicRequest.get(
uri"https://api.github.com/search/repositories?q=$query&sort=$sort")
val backend = DefaultSyncBackend()
val response = request.send(backend)
// response.header(...): Option[String]
println(response.header("Content-Length"))
// response.body: read into an Either[String, String] to indicate failure or success
println(response.body)
But that’s just a small glimpse of sttp client’s features! For more examples, see the usage examples section.
To start using sttp client in your project, see the quickstart. Or, browse the documentation to find the topics that interest you the most! ScalaDoc is available at https://www.javadoc.io.
sttp client is licensed under Apache2, the source code is available on GitHub.
Other sttp projects
sttp is a family of Scala HTTP-related projects, and currently includes:
sttp client: this project
sttp tapir: rapid development of self-documenting APIs
sttp model: simple HTTP model classes (used by client & tapir)
sttp shared: shared web socket, FP abstractions, capabilities and streaming code.
sttp apispec: OpenAPI, AsyncAPI and JSON Schema models.
sttp openai: Scala client wrapper for OpenAI and OpenAI-compatible APIs. Use the power of ChatGPT inside your code!
Third party projects:
sttp-oauth2: OAuth2 client library for Scala
Try sttp client in your browser!
Table of contents
Getting started
How-to's
HTTP model
Request definition
Responses
Other topics
Backends
Backend wrappers
Configuration
More information