Repository files navigation

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 usingscala-cli:

//>usingdepcom.softwaremill.sttp.client4::core:4.0.13importsttp.client4.quick.*@maindefrun():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'sHttpClient, 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:

//>usingdepcom.softwaremill.sttp.client4::core:4.0.13importsttp.client4.*@maindefsttpDemo():Unit=valsort:Option[String]=Nonevalquery="http language:scala"// the `query` parameter is automatically url-encoded// `sort` is removed, as the value is not definedvalrequest= basicRequest.get(uri"https://api.github.com/search/repositories?q=$query&sort=$sort")valbackend=DefaultSyncBackend()valresponse= 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 theusage examples.

sttp (v4) documentation is available atsttp.softwaremill.com.

sttp (v3) documentation is available atsttp.softwaremill.com/en/v3.

sttp (v2) documentation is available atsttp.softwaremill.com/en/v2.

sttp (v1) documentation is available atsttp.softwaremill.com/en/v1.

scaladoc is available athttps://www.javadoc.io

Add the following directive to the top of your scala file to add the core sttp dependency:If you are usingscala-cli, you can quickly start experimenting with sttp by copy-pasting the following:

//> using dep "com.softwaremill.sttp.client4::core:4.0.13"import sttp.client4.quick.*quickRequest.get(uri"http://httpbin.org/ip").send()

Thequick package import brings in the sttp API and a pre-configured, global synchronous backend instance.

Similarly, usingAmmonite:

import$ivy.`com.softwaremill.sttp.client4::core:4.0.13`importsttp.client4.quick.*quickRequest.get(uri"http://httpbin.org/ip").send()

Add the following dependency:

"com.softwaremill.sttp.client4"%%"core"%"4.0.13"

Then, import:

importsttp.client4.*

TypebasicRequest. and see where your IDE’s auto-complete gets you!

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!

If you have a question, suggestion, or hit a problem, feel free to ask on ourdiscourse forum!

Or, if you encounter a bug, something is unclear in the code or documentation, don’t hesitate and open an issue on GitHub.

We are also always looking for contributions and new ideas, so if you’d like to get into the project, check out theopen issues, or post your own suggestions!

Note that running the defaultcompile andtest tasks will build all of the JVM, Native and JS backends, and is likely to run out of memory, or to encounter missing native dependencies. If you'd like to run compilation/tests usingonly the JVM backend, run:sbt "compileScoped 3 JVM" orsbt "testScoped 3 JVM".

When you have a PR ready, take a look at our"How to prepare a good PR" guide. Thanks! :)

By default, when importing to IntelliJ or Metals, only the Scala 2.13/JVM subprojects will be imported. This is controlled by theideSkipProject setting inbuild.sbt (insidecommonSettings).

If you'd like to work on a different platform or Scala version, simply change this setting temporarily so that the correct subprojects are imported. For example:

// import only Scala 2.13, JS projectsideSkipProject := (scalaVersion.value != scala2_13) || !thisProjectRef.value.project.contains("JS")// import only Scala 3, JVM projectsideSkipProject := (scalaVersion.value != scala3) || thisProjectRef.value.project.contains("JS") || thisProjectRef.value.project.contains("Native"),// import only Scala 2.13, Native projectsideSkipProject := (scalaVersion.value != scala2_13) || !thisProjectRef.value.project.contains("Native")

The documentation is typechecked usingmdoc. The sources for the documentation exist indocs. Don't modify the generated documentation ingenerated-docs, as these files will get overwritten!

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 ThisBuild/version := "4.0.13", before runningmdoc indocs.

In order to run tests against JS backend you will need to installGoogle Chrome.

By default, sttp-native willnot be included in the aggregate build of the root project. To include it, define theSTTP_NATIVE environmental variable before running sbt, e.g.:

STTP_NATIVE=1 sbt

You might need to install some additional libraries, see thescala native documentation site. On macos, you might additionally need:

ln -s /usr/local/opt/openssl/lib/libcrypto.dylib /usr/local/lib/ln -s /usr/local/opt/openssl/lib/libssl.dylib /usr/local/lib/

We offer commercial support for sttp and related technologies, as well as development services.Contact us to learn more about our offer!

Copyright (C) 2017-2025 SoftwareMillhttps://softwaremill.com.