sttp: the Scala HTTP client you always wanted!

Welcome!

sttp client is an open-source library which provides a clean, programmer-friendly API to describe HTTP requests and execute them using one of the wrapped backends, such as akka-http, async-http-client, http4s or OkHttp.

Here’s a very quick example of sttp client in action:

import sttp.client._

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")

implicit val backend = HttpURLConnectionBackend()
val response = request.send()

// response.header(...): Option[String]
println(response.header("Content-Length"))

// response.unsafeBody: by default read into a String
println(response.unsafeBody)

For more examples, see the usage examples section. Or explore the features in detail:

Getting started

• Quickstart
  • Using sbt
  • Using Ammonite
  • Imports
• Goals of the project
  • Non-goals of the project
  • How is sttp different from other libraries?
• Community
• Usage examples
  • POST a form using the synchronous backend
  • GET and parse JSON using the akka-http backend and json4s
  • Test an endpoint requiring multiple parameters

HTTP model

• Model classes
• URIs
  • URI interpolator
  • Optional values
  • Maps and sequences
  • Special cases
  • All features combined

Request definition

• Request definition basics
  • Sending a request
  • Starting requests
  • Debugging requests
• Headers
  • Common headers
• Cookies
  • Cookies from responses
• Authentication
  • Digest authentication
• Setting the request body
  • Text data
  • Binary data
  • Uploading files
  • Form data
  • Custom body serializers
• Multipart requests
  • Customising part meta-data
• Streaming
• Websockets
  • Low-level and high-level websocket handlers
• The type of request definitions

Responses

• Responses
  • Response code
  • Response headers
  • Obtaining the response body
• Response body specification
  • Basic response specifications
  • Custom body deserializers
  • Streaming

Backends

• Supported backends
• Starting & cleaning up
• HttpURLConnection backend
• akka-http backend
  • Testing
  • Websockets
• async-http-client backend
  • Streaming using Monix
  • Streaming using fs2
  • Websockets
  • Streaming websockets using fs2
• OkHttp backend
  • Websockets
• Http4s backend
• Finagle backend
• HttpClient backend (Java 11+)
  • Websockets
• Opentracing backend
  • Integration with jaeger
  • Integration with brave
• brave backend (deprecated)
• Prometheus backend
• Fetch backend
  • Node.js
  • Streaming
• Custom backends, logging, metrics
  • Request tagging
  • Backend wrappers and redirects
  • Example logging backend wrapper
  • Example metrics backend wrapper
  • Example retrying backend wrapper
  • Example backend with circuit breaker
  • Example backend with rate limiter
  • Example new backend

Testing

• Testing
  • Creating a stub backend
  • Specifying behavior
  • Simulating exceptions
  • Adjusting the response body type
  • Example: returning JSON
  • Example: returning a file
  • Delegating to another backend

Configuration

• Timeouts
• SSL
• Proxy support
• Redirects
  • Redirecting POST requests

More information

• JSON
  • Circe
  • Json4s
  • spray-json
  • play-json
• Other Scala HTTP clients

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)