sttp

https://sttp.softwaremill.com/en/stable
Admin
sttp is an open-source HTTP client for Scala that supports synchronous, Future-based, and functional...
Tokens:71,502
Snippets:765
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### scala-cli example with CurlBackend

Source: https://sttp.softwaremill.com/en/stable/backends/native/curl.html

A complete scala-cli example that sends a GET request to httpbin.org/ip using CurlBackend. Requires Scala Native setup with libcrypto and curl.

```scala
// hello.scala

//> using platform native
//> using dep com.softwaremill.sttp.client4::core_native0.5:4.0.26

import sttp.client4.*
import sttp.client4.curl.CurlBackend

@main def run(): Unit =
  val backend = CurlBackend()
  println(basicRequest.get(uri"http://httpbin.org/ip").send(backend))
```

--------------------------------

### Standalone setup

Source: https://sttp.softwaremill.com/en/stable/other/openapi.html

Command to generate a complete sbt project from an OpenAPI specification using the standalone setup.

```bash
openapi-generator-cli generate \
  -i petstore.yaml \
  --generator-name scala-sttp4-jsoniter \
  -o samples/client/petstore/

```

--------------------------------

### Quick example using quickRequest and scala-cli

Source: https://sttp.softwaremill.com/en/stable/index.html

Runnable with scala-cli, this snippet shows the simplest way to send a GET request using sttp client's quick API. It requires the core dependency version 4.0.26 and prints the response body.

```scala
//> using dep com.softwaremill.sttp.client4::core::4.0.26

import sttp.client4.quick.*

@main def run(): Unit =
  println(quickRequest.get(uri"http://httpbin.org/ip").send())

```

--------------------------------

### Sbt managed setup - final configuration

Source: https://sttp.softwaremill.com/en/stable/other/openapi.html

Final petstore module configuration with all settings.

```scala
lazy val petstoreApi: Project = project
  .in(file("petstore-api"))
  .settings(
    openApiInputSpec := s"${baseDirectory.value.getPath}/petstore.yaml",
    openApiGeneratorName := "scala-sttp4-jsoniter",
    openApiOutputDir := baseDirectory.value.name,
    openApiIgnoreFileOverride := s"${baseDirectory.in(ThisBuild).value.getPath}/openapi-ignore-file",
    libraryDependencies ++= Seq(
      "com.softwaremill.sttp.client4" %% "core" % "4.0.26",
      "com.softwaremill.sttp.client4" %% "json4s" % "4.0.26",
      "org.json4s" %% "json4s-native" % "4.0.7"
    ),
    (compile in Compile) := ((compile in Compile) dependsOn openApiGenerate).value,
    cleanFiles += baseDirectory.value / "src"
  )

```

--------------------------------

### ZIO-based example with CurlZioBackend.scoped()

Source: https://sttp.softwaremill.com/en/stable/backends/native/curl.html

Create a ZIO backend using scoped() to ensure resources are released. The example sends a GET request and prints the response.

```scala
//> using platform native
//> using nativeVersion 0.5.10
//> using scala 3
//> using dep com.softwaremill.sttp.client4::zio::4.0.26

import sttp.client4.*
import sttp.client4.curl.zio.CurlZioBackend
import zio.*

object Main extends ZIOAppDefault:
  def run = for
    backend <- CurlZioBackend.scoped()
    res <- basicRequest.get(uri"http://httpbin.org/ip").send(backend)
    _ <- Console.printLine(res)    
  yield ()
```

--------------------------------

### ZIO layer example: MyService with HttpClientZioBackend.layer()

Source: https://sttp.softwaremill.com/en/stable/backends/zio.html

Shows how to define a service that depends on a Backend[Task] and provide it via a ZLayer, using HttpClientZioBackend.layer() to create the backend layer. The example includes the service class, its live layer, and the composition with ZLayer.make.

```scala
import sttp.client4.*
import sttp.client4.httpclient.zio.*
import zio.*

class MyService(sttpBackend: Backend[Task]) {
  def runLogic(): Task[Response[String]] = {
    val request = basicRequest.response(asStringAlways).get(uri"https://httpbin.org/get")
    request.send(sttpBackend)
  }
}

object MyService {
  val live: ZLayer[Backend[Task], Any, MyService] = ZLayer.fromFunction(new MyService(_))
}

ZLayer.make[MyService](MyService.live, HttpClientZioBackend.layer())

```

--------------------------------

### Install Node.js modules for ESModule

Source: https://sttp.softwaremill.com/en/stable/backends/javascript/fetch.html

Install the required Node.js modules for using FetchBackend with ESModule.

```shell
npm install --save node-fetch isomorphic-ws ws

```

--------------------------------

### ZIO environment: send request using SttpClient

Source: https://sttp.softwaremill.com/en/stable/backends/zio.html

Shows how to send a request using the top-level send method that requires a SttpClient in the ZIO environment. The example creates a basic GET request and returns a ZIO effect that will be executed when the environment provides the SttpClient.

```scala
import sttp.client4.*
import sttp.client4.httpclient.zio.*
import zio.*

val request = basicRequest.get(uri"https://httpbin.org/get")
val sent: ZIO[SttpClient, Throwable, Response[Either[String, String]]] = 
  send(request)

```

--------------------------------

### Fully-featured URI interpolation example

Source: https://sttp.softwaremill.com/en/stable/model/uri.html

A fully-featured example showing URI interpolation with scheme, subdomains, optional query parameter, query map, and fragment. The output demonstrates how each component is interpolated and encoded.

```scala
import sttp.client4.*
val secure = true
val scheme = if (secure) "https" else "http"
val subdomains = List("sub1", "sub2")
val vx = Some("y z")
val paramMap = Map("a" -> 1, "b" -> 2)
val jumpTo = Some("section2")

```

```scala
println(uri"$scheme://$subdomains.example.com?x=$vx&$paramMap#$jumpTo")
// https://sub1.sub2.example.com?x=y+z&a=1&b=2#section2

```

--------------------------------

### Sbt managed setup - ignore file content

Source: https://sttp.softwaremill.com/en/stable/other/openapi.html

Content of the openapi-ignore-file to exclude everything except source files.

```text
*
**/*
!**/src/main/scala/**/*

```

--------------------------------

### Capture interactions with RecordingBackend

Source: https://sttp.softwaremill.com/en/stable/testing/stub.html

Wrap a backend stub with RecordingBackend to capture all interactions. The example shows a stub that responds to requests whose URI path starts with "a" and "b", then sends a request and inspects the recorded interactions list for verification.

```scala
import scala.util.Try

val testingBackend = RecordingBackend(
  SyncBackendStub
    .whenRequestMatches(_.uri.path.startsWith(List("a", "b")))
    .thenRespondAdjust("Hello there!")
)

val response1 = basicRequest.get(uri"http://example.org/a/b/c").send(testingBackend)
// response1.body will be Right("Hello there")

testingBackend.allInteractions: List[(GenericRequest[_, _], Try[Response[_]])]
// the list will contain one element and can be verified in a test
```

--------------------------------

### Create backend from a Route for testing

Source: https://sttp.softwaremill.com/en/stable/backends/pekko.html

Create a backend using a pekko-http Route to mock a server without starting an actual server. Useful for testing client libraries against routes.

```scala
import sttp.client4.pekkohttp.*
import org.apache.pekko
import pekko.http.scaladsl.server.Route
import pekko.actor.ActorSystem

val route: Route = ???
implicit val system: ActorSystem = ???

val backend = PekkoHttpBackend.usingClient(system, http = PekkoHttpClient.stubFromRoute(route))

```

--------------------------------

### Digest Authentication Backend Setup

Source: https://sttp.softwaremill.com/en/stable/requests/authentication.html

Wraps a backend with DigestAuthenticationBackend to handle the digest authentication handshake.

```scala
import sttp.client4.wrappers.DigestAuthenticationBackend

val myBackend: SyncBackend = DefaultSyncBackend()
DigestAuthenticationBackend(myBackend)
```

--------------------------------

### Install Node.js modules for CommonJS

Source: https://sttp.softwaremill.com/en/stable/backends/javascript/fetch.html

Install the required Node.js modules for using FetchBackend with CommonJS. Node-fetch version 2 is required because version 3 is not available as a CommonJS module.

```shell
npm install --save node-fetch@2 isomorphic-ws ws

```

--------------------------------

### Sbt managed setup - clean files

Source: https://sttp.softwaremill.com/en/stable/other/openapi.html

Attach generated source code directory to cleaning process.

```scala
cleanFiles += baseDirectory.value / "src"
```

--------------------------------

### Sbt managed setup

Source: https://sttp.softwaremill.com/en/stable/other/openapi.html

Sbt module definition for generating sttp client from OpenAPI specification.

```scala
lazy val petstoreApi: Project = project
  .in(file("petstore-api"))
  .settings(
    openApiInputSpec := s"${baseDirectory.value.getPath}/petstore.yaml",
    openApiGeneratorName := "scala-sttp4-jsoniter",
    openApiOutputDir := baseDirectory.value.name,
    libraryDependencies ++= Seq(
      "com.softwaremill.sttp.client4" %% "core" % "4.0.26",
      "com.softwaremill.sttp.client4" %% "json4s" % "4.0.26",
      "org.json4s" %% "json4s-native" % "4.0.7"
    )
  )
```

--------------------------------

### Create ArmeriaCatsBackend with custom WebClient

Source: https://sttp.softwaremill.com/en/stable/backends/catseffect.html

Create the backend with a custom Armeria WebClient. The example builds a client with a circuit breaker decorator that opens on 5xx server errors. Note that a WebClient with a base URI may fail to follow redirects to a different URI.

```scala
import cats.effect.IO
import com.linecorp.armeria.client.WebClient
import com.linecorp.armeria.client.circuitbreaker._
import sttp.client4.armeria.cats.ArmeriaCatsBackend

// Fluently build Armeria WebClient with built-in decorators
val client = WebClient.builder("https://my-service.com")
             // Open circuit on 5xx server error status
             .decorator(CircuitBreakerClient.newDecorator(CircuitBreaker.ofDefaultName(),
               CircuitBreakerRule.onServerErrorStatus()))
             .build()

val backend = ArmeriaCatsBackend.usingClient[IO](client)

```

--------------------------------

### Create backend from akka-http Route for testing

Source: https://sttp.softwaremill.com/en/stable/backends/akka.html

Create a backend using an akka-http Route to mock a server without starting any actual server or making HTTP calls. Useful for testing client libraries against the routes exposed by an application.

```scala
import sttp.client4.akkahttp._
import akka.http.scaladsl.server.Route
import akka.actor.ActorSystem

val route: Route = ???
implicit val system: ActorSystem = ???

val backend = AkkaHttpBackend.usingClient(system, http = AkkaHttpClient.stubFromRoute(route))

```

--------------------------------

### Use Slf4jLoggingBackend

Source: https://sttp.softwaremill.com/en/stable/backends/wrappers/logging.html

Example usage of the slf4j logging backend wrapper. It logs request and response information using a slf4j Logger; you need an slf4j-compatible logger implementation (e.g., logback) or a binding (e.g., log4j-slf4j) to see the logs.

```scala
import sttp.client4.*
import sttp.client4.logging.slf4j.Slf4jLoggingBackend

val backend = Slf4jLoggingBackend(DefaultSyncBackend())
basicRequest.get(uri"https://httpbin.org/get").send(backend)

// Logs:
// 21:14:23.735 [main] INFO sttp.client4.logging.slf4j.Slf4jTimingBackend - Request: GET https://httpbin.org/get, took: 0.795s, response: 200
```

--------------------------------

### Example with objects: Header.contentType and MediaType.ApplicationJson

Source: https://sttp.softwaremill.com/en/stable/model/model.html

Uses the sttp model companion objects directly, such as Header.contentType and MediaType.ApplicationJson, to build a request and check the response status code. Requires the sttp.client4 and sttp.model imports. Prints "Ok!" when the response code equals StatusCode.Ok.

```scala
import sttp.client4.*
import sttp.model.*

object Example:
  val request = basicRequest.header(Header.contentType(MediaType.ApplicationJson))
    .get(uri"https://httpbin.org")

  val backend = DefaultSyncBackend()
  val response = request.send(backend)
  if response.code == StatusCode.Ok then println("Ok!")

```

--------------------------------

### Initialize CurlBackend and CurlTryBackend

Source: https://sttp.softwaremill.com/en/stable/backends/native/curl.html

Import the curl package and create backend instances. CurlBackend is the default, CurlTryBackend is also available.

```scala
import sttp.client4.curl.*

val backend = CurlBackend()
val tryBackend = CurlTryBackend()
```

--------------------------------

### Import sttp.client4 package

Source: https://sttp.softwaremill.com/en/stable/quickstart.html

Imports the entire sttp.client4 package, bringing basicRequest and helper methods into scope. All examples in this guide assume this import.

```scala
import sttp.client4.*
```

--------------------------------

### Create a Scalaz backend with ArmeriaScalazBackend() or usingDefaultClient()

Source: https://sttp.softwaremill.com/en/stable/backends/scalaz.html

Shows two ways to create the backend: default constructor and the default client with the shared connection pool from ClientFactory.ofDefault().

```scala
val backend = ArmeriaScalazBackend()

// You can use the default client which reuses the connection pool of ClientFactory.ofDefault()
ArmeriaScalazBackend.usingDefaultClient()
```

--------------------------------

### Create HttpClientZioBackend

Source: https://sttp.softwaremill.com/en/stable/backends/zio.html

Shows various ways to create the ZIO backend: using the default constructor, scoped, using a custom HttpClient, and scoped with a custom client.

```scala
import sttp.client4.httpclient.zio.HttpClientZioBackend

HttpClientZioBackend().flatMap { backend => ??? }

// or, if you'd like the backend to be created in a Scope:
HttpClientZioBackend.scoped().flatMap { backend => ??? }

// or, if you'd like to instantiate the HttpClient yourself:
import java.net.http.HttpClient
val httpClient: HttpClient = ???
val backend = HttpClientZioBackend.usingClient(httpClient)

// or, obtain a Scope with a custom instance of the HttpClient:
HttpClientZioBackend.scopedUsingClient(httpClient).flatMap { backend => ??? }
```

--------------------------------

### Create FetchZioBackend instance

Source: https://sttp.softwaremill.com/en/stable/backends/javascript/fetch.html

Create the ZIO-based Fetch backend instance.

```scala
val backend = FetchZioBackend()

```

--------------------------------

### Create ArmeriaZioBackend client

Source: https://sttp.softwaremill.com/en/stable/backends/zio.html

Create a client using ArmeriaZioBackend(). Optionally wrap in a Scope with .scoped(), or use the default client with .usingDefaultClient().

```scala
ArmeriaZioBackend().flatMap { backend => ??? }

// or, if you'd like the backend to be wrapped in a Scope:
ArmeriaZioBackend.scoped().flatMap { backend => ??? }

// You can use the default client which reuses the connection pool of ClientFactory.ofDefault()
ArmeriaZioBackend.usingDefaultClient().flatMap { backend => ??? }

```

--------------------------------

### Sample data classes for JSON examples

Source: https://sttp.softwaremill.com/en/stable/other/json.html

Defines the RequestPayload and ResponsePayload case classes used in the following examples on this page.

```scala
case class RequestPayload(data: String)
case class ResponsePayload(data: String)
```

--------------------------------

### Create FetchMonixBackend instance

Source: https://sttp.softwaremill.com/en/stable/backends/javascript/fetch.html

Create the Monix-based Fetch backend instance.

```scala
val backend = FetchMonixBackend()

```

--------------------------------

### Convert POST/PUT redirects to GET

Source: https://sttp.softwaremill.com/en/stable/conf/redirects.html

Use the redirectToGet method to force the client to issue a GET request when a POST or PUT request is redirected.

```scala
import sttp.client4.*

basicRequest.redirectToGet(true)
```

--------------------------------

### Common imports and User case class for stub backend examples

Source: https://sttp.softwaremill.com/en/stable/testing/stub.html

Common imports and a sample User case class used by the stub backend examples on this page.

```scala
import sttp.client4.*
import sttp.model.*
import sttp.client4.testing.*
import java.io.File
import scala.concurrent.Future
import scala.concurrent.ExecutionContext.Implicits.global

case class User(id: String)

```

--------------------------------

### Create PekkoHttpBackend with existing ActorSystem

Source: https://sttp.softwaremill.com/en/stable/backends/pekko.html

Create a PekkoHttpBackend using an existing actor system. The actor system must be provided.

```scala
import sttp.client4.pekkohttp.*
import org.apache.pekko.actor.ActorSystem

val actorSystem: ActorSystem = ???
val backend = PekkoHttpBackend.usingActorSystem(actorSystem)

```

--------------------------------

### Create OkHttp Monix backend

Source: https://sttp.softwaremill.com/en/stable/backends/monix.html

Create an OkHttp backend for Monix using the default factory, a cats-effect Resource, or a custom OkHttpClient instance.

```scala
import sttp.client4.okhttp.monix.OkHttpMonixBackend

OkHttpMonixBackend().flatMap { backend => ??? }

// or, if you'd like the backend to be wrapped in cats-effect Resource:
OkHttpMonixBackend.resource().use { backend => ??? }

// or, if you'd like to instantiate the OkHttpClient yourself:
import okhttp3._
val okHttpClient: OkHttpClient = ???
val backend = OkHttpMonixBackend.usingClient(okHttpClient)

```

--------------------------------

### Create Armeria Monix backend

Source: https://sttp.softwaremill.com/en/stable/backends/monix.html

Create an Armeria backend for Monix using the default client or the default client factory.

```scala
import monix.execution.Scheduler.Implicits.global
val backend = ArmeriaMonixBackend()

// You can use the default client which reuses the connection pool of ClientFactory.ofDefault()
ArmeriaMonixBackend.usingDefaultClient()

```

--------------------------------

### Sbt managed setup - compile dependency

Source: https://sttp.softwaremill.com/en/stable/other/openapi.html

Connect generation with compilation in sbt module settings.

```scala
(compile in Compile) := ((compile in Compile) dependsOn openApiGenerate).value,
```

--------------------------------

### Create OkHttpFutureBackend with custom OkHttpClient

Source: https://sttp.softwaremill.com/en/stable/backends/future.html

Creates a backend using a custom OkHttpClient instance.

```scala
import okhttp3.OkHttpClient

val okHttpClient: OkHttpClient = ??? 
val backend = OkHttpFutureBackend.usingClient(okHttpClient)
```

--------------------------------

### Create a Scalaz backend with a custom Armeria WebClient

Source: https://sttp.softwaremill.com/en/stable/backends/scalaz.html

Builds a WebClient with a circuit breaker decorator and then creates the backend using that client. Shows a client with a base URI and a circuit breaker rule on server errors.

```scala
import com.linecorp.armeria.client.circuitbreaker._
import com.linecorp.armeria.client.WebClient

// Fluently build Armeria WebClient with built-in decorators
val client = WebClient.builder("https://my-service.com")
             // Open circuit on 5xx server error status
             .decorator(CircuitBreakerClient.newDecorator(CircuitBreaker.ofDefaultName(),
               CircuitBreakerRule.onServerErrorStatus()))
             .build()

val backend = ArmeriaScalazBackend.usingClient(client)
```

--------------------------------

### Sbt managed setup - ignore file override

Source: https://sttp.softwaremill.com/en/stable/other/openapi.html

Tell openapi-generator not to generate whole project but only source files.

```scala
openApiIgnoreFileOverride := s"${baseDirectory.in(ThisBuild).value.getPath}/openapi-ignore-file",
```

--------------------------------

### Create AkkaHttpBackend with existing ActorSystem

Source: https://sttp.softwaremill.com/en/stable/backends/akka.html

Create an AkkaHttpBackend using an existing actor system.

```scala
import sttp.client4.akkahttp._
import akka.actor.ActorSystem

val actorSystem: ActorSystem = ???
val backend = AkkaHttpBackend.usingActorSystem(actorSystem)

```

--------------------------------

### OAuth2 token request

Source: https://sttp.softwaremill.com/en/stable/requests/authentication.html

Example of sending a request to an authentication server to exchange an authorization code for an access token.

```APIDOC
## POST https://github.com/login/oauth/access_token

### Description
Send a POST request to the authentication server to exchange an authorization code for an access token.

### Method
POST

### Endpoint
https://github.com/login/oauth/access_token

### Query Parameters
- **code** (String) - Required - The authorization code received in the callback.
- **grant_type** (String) - Required: The grant type, typically 'authorization_code'.

### Headers
- **Authorization** - Basic auth using client ID and client secret.
- **accept** - application/json

### Request Body
None

### Response
JSON containing access_token, scope, token_type, refresh_token (optional).

### Example Request
```
POST https://github.com/login/oauth/access_token?code=SplxlOBeZQQYbYS6WxSbIA&grant_type=authorization_code
Authorization: Basic base64(clientId:clientSecret)
accept: application/json
```

### Example Code
```scala
import sttp.client4.circe.*
import io.circe.*
import io.circe.generic.semiauto.*

val authCode = "SplxlOBeZQQYbYS6WxSbIA"
val clientId = "myClient123"
val clientSecret = "s3cret"
case class MyTokenResponse(access_token: String, scope: String, token_type: String, refresh_token: Option[String])
implicit val tokenResponseDecoder: Decoder[MyTokenResponse] = deriveDecoder[MyTokenResponse]
val backend = DefaultSyncBackend()

val tokenRequest = basicRequest
    .post(uri"https://github.com/login/oauth/access_token?code=$authCode&grant_type=authorization_code")
    .auth
    .basic(clientId, clientSecret)
    .header("accept","application/json")
val authResponse = tokenRequest.response(asJson[MyTokenResponse]).send(backend)
val accessToken = authResponse.body.map(_.access_token)
```
```

--------------------------------

### OAuth2 Token Exchange Request

Source: https://sttp.softwaremill.com/en/stable/requests/authentication.html

Example of exchanging an authentication code for an access token using GitHub as the provider.

```scala
import sttp.client4.circe.*
import io.circe.*
import io.circe.generic.semiauto.*

val authCode = "SplxlOBeZQQYbYS6WxSbIA"
val clientId = "myClient123"
val clientSecret = "s3cret"
case class MyTokenResponse(access_token: String, scope: String, token_type: String, refresh_token: Option[String])
implicit val tokenResponseDecoder: Decoder[MyTokenResponse] = deriveDecoder[MyTokenResponse]
val backend = DefaultSyncBackend()

val tokenRequest = basicRequest
    .post(uri"https://github.com/login/oauth/access_token?code=$authCode&grant_type=authorization_code")
    .auth
    .basic(clientId, clientSecret)
    .header("accept","application/json")
val authResponse = tokenRequest.response(asJson[MyTokenResponse]).send(backend)
val accessToken = authResponse.body.map(_.access_token)
```

--------------------------------

### Handle SSE as a Flow with Ox

Source: https://sttp.softwaremill.com/en/stable/backends/synchronous.html

Example of handling server-sent events as a Flow[ServerSentEvent] using OxServerSentEvents and DefaultSyncBackend.

```scala
import sttp.client4.*
import sttp.client4.impl.ox.sse.OxServerSentEvents
import java.io.InputStream

def handleSse(is: InputStream): Unit =
  OxServerSentEvents.parse(is).runForeach(event => println(s"Received event: $event"))

val backend = DefaultSyncBackend()
  basicRequest
    .get(uri"https://postman-echo.com/server-events/3")
    .response(asInputStreamAlways(handleSse))
    .send(backend)

```

--------------------------------

### Create ArmeriaFutureBackend

Source: https://sttp.softwaremill.com/en/stable/backends/future.html

Creates a default ArmeriaFutureBackend and shows using the default client.

```scala
val backend = ArmeriaFutureBackend()

// You can use the default client which reuses the connection pool of ClientFactory.ofDefault()
ArmeriaFutureBackend.usingDefaultClient()
```

--------------------------------

### Use quick backend with quickRequest

Source: https://sttp.softwaremill.com/en/stable/quickstart.html

Use the quick backend to send a request without creating a backend instance. The backend is global, created on first access, cannot be customized, and should not be closed. quickRequest reads responses as String regardless of status code.

```scala
import sttp.client4.quick.*
quickRequest.get(uri"http://httpbin.org/ip").send()
```

--------------------------------

### Add pekko-stream dependency

Source: https://sttp.softwaremill.com/en/stable/backends/pekko.html

Add an explicit dependency on pekko-streams because pekko-http does not depend on a specific version. Example uses version 1.6.0.

```scala
"org.apache.pekko" %% "pekko-stream" % "1.6.0"

```

--------------------------------

### Import Armeria Monix backend

Source: https://sttp.softwaremill.com/en/stable/backends/monix.html

Import the Armeria Monix backend class.

```scala
import sttp.client4.armeria.monix.ArmeriaMonixBackend

```

--------------------------------

### Stub with cyclic responses

Source: https://sttp.softwaremill.com/en/stable/testing/stub.html

Defines a sequence of responses that are served cyclically. Each request gets the next response in the list, wrapping around to the first after the last.

```scala
val testingBackend: SyncBackendStub = SyncBackendStub
  .whenAnyRequest
  .thenRespondCyclic(
    ResponseStub.adjust("first"),
    ResponseStub.adjust("error", StatusCode.InternalServerError)
  )

basicRequest.get(uri"http://example.org").send(testingBackend)       // code will be 200
basicRequest.get(uri"http://example.org").send(testingBackend)       // code will be 500
basicRequest.get(uri"http://example.org").send(testingBackend)       // code will be 200
```

--------------------------------

### Stub response depending on the request

Source: https://sttp.softwaremill.com/en/stable/testing/stub.html

The response is computed based on the incoming request. The example uses the request's URI host to build the response body.

```scala
val testingBackend = SyncBackendStub
  .whenAnyRequest
  .thenRespondF(req =>
    ResponseStub.adjust(s"OK, got request sent to ${req.uri.host}")
  )

val response = basicRequest.get(uri"http://example.org").send(testingBackend)
// response.body will be Right("OK, got request sent to example.org")
```

--------------------------------

### Create OkHttpFutureBackend with SSLContext

Source: https://sttp.softwaremill.com/en/stable/conf/ssl.html

Builds an OkHttpClient with the SSLContext and an explicit X509TrustManager, then creates an OkHttpFutureBackend. The trust manager must be provided; it can be extracted from the TrustManagerFactory from the mutual SSL section.

```scala
import okhttp3.OkHttpClient
import sttp.client4.okhttp.OkHttpFutureBackend
import javax.net.ssl.X509TrustManager

val yourTrustManager: X509TrustManager = ???

val client: OkHttpClient = new OkHttpClient.Builder()
  .sslSocketFactory(ssl.getSocketFactory, yourTrustManager)
  .build()

val backend = OkHttpFutureBackend.usingClient(client)

```

--------------------------------

### Create OkHttpSyncBackend with custom OkHttpClient

Source: https://sttp.softwaremill.com/en/stable/backends/synchronous.html

Creates a synchronous backend using a custom okhttp3.OkHttpClient instance.

```scala
import sttp.client4.okhttp.OkHttpSyncBackend
import okhttp3.*

val okHttpClient: OkHttpClient = ???
val backend = OkHttpSyncBackend.usingClient(okHttpClient)

```

--------------------------------

### Convert PEM credentials to .p12 with openssl

Source: https://sttp.softwaremill.com/en/stable/conf/ssl.html

Converts PEM-format client credentials to a .p12 keystore, which is required by the one-way SSL example. Run this before creating the SSLContext.

```bash
openssl pkcs12 -export -inkey your_key.pem -in your_cert.pem -out your_cert.p12
```

--------------------------------

### Create backend with HTTP proxy

Source: https://sttp.softwaremill.com/en/stable/conf/proxy.html

Creates a synchronous backend with an HTTP proxy and sends a GET request through it. The proxy is specified via BackendOptions.httpProxy("some.host", 8080).

```scala
import sttp.client4.*

val backend = DefaultSyncBackend(
  options = BackendOptions.httpProxy("some.host", 8080))

basicRequest
  .get(uri"...")
  .send(backend) // uses the proxy

```

--------------------------------

### Create OkHttpFutureBackend

Source: https://sttp.softwaremill.com/en/stable/backends/future.html

Creates a default OkHttpFutureBackend instance.

```scala
val backend = OkHttpFutureBackend()
```

--------------------------------

### Import ArmeriaZioBackend

Source: https://sttp.softwaremill.com/en/stable/backends/zio.html

Import the ArmeriaZioBackend class.

```scala
import sttp.client4.armeria.zio.ArmeriaZioBackend

```

--------------------------------

### Use HeaderNames constants for header names

Source: https://sttp.softwaremill.com/en/stable/requests/headers.html

Uses the HeaderNames object from sttp model to avoid string literals for header names. The example sets the Cache-Control header using the CacheDirective.MaxAge value.

```scala
import sttp.client4.*
import sttp.model.HeaderNames
import sttp.model.headers.CacheDirective
import scala.concurrent.duration.*

basicRequest.header(HeaderNames.CacheControl, CacheDirective.MaxAge(1.day).toString)

```

--------------------------------

### Add TrustManagerFactory for mutual SSL

Source: https://sttp.softwaremill.com/en/stable/conf/ssl.html

Extends the one-way SSL example to mutual SSL by loading the server trust store and initializing a TrustManagerFactory. The SSLContext is then initialized with both key managers and trust managers.

```scala
ks.load(new FileInputStream("/path/to/server_trust"), "password".toCharArray)

val tmf: TrustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm) 
tmf.init(ks)

val ssl: SSLContext = SSLContext.getInstance("TLS")
ssl.init(kmf.getKeyManagers, tmf.getTrustManagers, new SecureRandom)

```

--------------------------------

### Create FinagleBackend instance

Source: https://sttp.softwaremill.com/en/stable/backends/finagle.html

Create a Finagle backend instance. Import the FinagleBackend class and instantiate it to use the asynchronous backend that wraps results in Twitter's Future.

```scala
import sttp.client4.finagle.FinagleBackend
val backend = FinagleBackend()

```

--------------------------------

### Configure Slf4jLoggingBackend

Source: https://sttp.softwaremill.com/en/stable/quickstart.html

Import the slf4j logging backend and wrap a backend instance to enable logging. Requests sent via this backend will be logged using slf4j.

```scala
import sttp.client4.*
import sttp.client4.logging.slf4j.Slf4jLoggingBackend

val backend = Slf4jLoggingBackend(DefaultSyncBackend())
```

--------------------------------

### Custom serializer for a case class returning BasicBody

Source: https://sttp.softwaremill.com/en/stable/requests/body.html

Shows how to write a custom serializer that returns a BasicBody instance. The example serializes a Person case class to CSV with a custom content type (text/csv).

```scala
import sttp.client4.*
import sttp.model.MediaType
case class Person(name: String, surname: String, age: Int)

// for this example, assuming names/surnames can't contain commas
def serializePerson(p: Person): BasicBody = { 
  val serialized = s"${p.name},${p.surname},${p.age}"
  StringBody(serialized, "UTF-8", MediaType.TextCsv)
}

basicRequest.body(serializePerson(Person("mary", "smith", 67)))

```
Tokens:
Raw