sttp: the Scala HTTP client you always wanted!
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, pekko-http, 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, Scala.JS and Scala Native.
Here’s a quick example of sttp client in action:
import sttp.client3._ val query = "http language:scala" val sort: Option[String] = None // 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 = HttpClientSyncBackend() val response = request.send(backend) // response.header(...): Option[String] println(response.header("Content-Length")) // response.body: by default read into an Either[String, String] // to indicate failure or success println(response.body)
Other sttp projects
sttp is a family of Scala HTTP-related projects, and currently includes:
sttp client: this project
sttp tapir: Typed API descRiptions
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.
Third party projects:
Try sttp client in your browser!
Development and maintenance of sttp client is sponsored by SoftwareMill, a software development and consulting company. We help clients scale their business through software. Our areas of expertise include backends, distributed systems, blockchain, machine learning and data analytics.
We offer commercial support for sttp and related technologies, as well as development services. Contact us to learn more about our offer!
Table of contents
- Simple synchronous client
- How sttp client works
- Goals of the project
- Usage examples
- Use the simple synchronous client
- POST a form using the synchronous backend
- GET and parse JSON using the akka-http backend and json4s
- GET and parse JSON using the ZIO http-client backend and circe
- GET and parse JSON using the http-client Monix backend and circe, treating deserialization errors as failed effects
- Log requests & responses using slf4j
- POST and serialize JSON using the Monix http-client backend and circe
- Test an endpoint which requires multiple query parameters
- Open a websocket using ZIO
- Open a websocket using FS2 streams
- Test Monix websockets
- Open a websocket using Akka
- Open a websocket using Pekko
- Open a websocket using Monix
- Stream request and response bodies using fs2
- Stream request and response bodies using zio-stream
- Retry a request using ZIO
- GET parsed and raw response bodies
- Request definition basics
- Multipart requests
- The type of request definitions
- Supported backends
- Starting & cleaning up
- Synchronous backends
- Akka backend
- Pekko backend
- Future-based backends
- Monix backends
- cats-effect backend
- fs2 backend
- Scalaz backend
- ZIO backends
- Http4s backend
- Twitter future (Finagle) backend
- Curl backend
- Prometheus backend
- Custom backends