• Stars
    star
    1,454
  • Rank 32,350 (Top 0.7 %)
  • Language
    Scala
  • License
    Apache License 2.0
  • Created over 7 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The Scala HTTP client you always wanted!

sttp

Ideas, suggestions, problems, questions CI Maven Central Open in Gitpod

The Scala HTTP client that 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 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 lower-level 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 the HTTP client that is shipped with Java, as well as ones based on akka-http, http4s, OkHttp. They integrate with Akka, Monix, fs2, cats-effect, scalaz and ZIO. Supported Scala versions include 2.12, 2.13 and 3, Scala.JS and Scala Native; supported Java versions include 11+.

Here's a quick example of sttp client in action:

import sttp.client4._

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: by default read into an Either[String, String] to indicate failure or success 
println(response.body)                                 

Documentation

sttp (v4) documentation is available at sttp.softwaremill.com/en/latest.

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

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

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

scaladoc is available at https://www.javadoc.io

Quickstart with scala-cli

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

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

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

Quickstart with Ammonite

Similarly, using Ammonite:

import $ivy.`com.softwaremill.sttp.client4::core:4.0.0-M12`
import sttp.client4.quick._
quickRequest.get(uri"http://httpbin.org/ip").send()

Quickstart with sbt

Add the following dependency:

"com.softwaremill.sttp.client4" %% "core" % "4.0.0-M12"

Then, import:

import sttp.client4._

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

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.

Contributing

If you have a question, suggestion, or hit a problem, feel free to ask on our discourse 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 the open issues, or post your own suggestions!

Note that running the default test task will run the tests using both the JVM and JS backends, and is likely to run out of memory. If you'd like to run the tests using only the JVM backend, execute: sbt rootJVM/test.

Importing into IntelliJ

By default, when importing to IntelliJ or Metals, only the Scala 2.13/JVM subprojects will be imported. This is controlled by the ideSkipProject setting in build.sbt (inside commonSettings).

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 projects
ideSkipProject := (scalaVersion.value != scala2_13) || !thisProjectRef.value.project.contains("JS")

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

// import only Scala 2.13, Native projects
ideSkipProject := (scalaVersion.value != scala2_13) || !thisProjectRef.value.project.contains("Native")

Modifying documentation

The documentation is typechecked using mdoc. The sources for the documentation exist in docs. Don't modify the generated documentation in generated-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 version := "4.0.0-M12", before running mdoc in docs.

Testing the Scala.JS backend

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

Building & testing the scala-native backend

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

STTP_NATIVE=1 sbt

You might need to install some additional libraries, see the scala 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/

Commercial Support

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

Copyright

Copyright (C) 2017-2024 SoftwareMill https://softwaremill.com.

More Repositories

1

elasticmq

In-memory message queue with an Amazon SQS-compatible interface. Runs stand-alone or embedded.
Scala
2,502
star
2

tapir

Rapid development of self-documenting APIs
Scala
1,363
star
3

macwire

Zero-cost, compile-time, type-safe dependency injection library.
Scala
1,266
star
4

quicklens

Modify deeply nested case class fields
Scala
822
star
5

magnolia

Easy, fast, transparent generic derivation of typeclass instances
Scala
765
star
6

bootzooka

Simple project to quickly start developing a Scala-based microservice or web application, without the need to write login, user registration etc.
Scala
695
star
7

codebrag

Your daily code review tool
Scala
651
star
8

akka-http-session

Web & mobile client-side akka-http sessions, with optional JWT support
Scala
440
star
9

ox

Safe direct-style concurrency and resiliency for Scala on the JVM
Scala
382
star
10

it-cfp-list

List of Call For Papers for IT conferences
374
star
11

retry

because you should never give up, at least not on the first try
Scala
351
star
12

diffx

Pretty diffs for scala case classes
Scala
344
star
13

kmq

Kafka-based message queue
Scala
330
star
14

scala-clippy

Good advice for Scala compiler errors
Scala
315
star
15

supler

Rapid Form Development library. Use your favourite JS frontend & Scala backend frameworks.
Scala
286
star
16

jox

Fast and Scalable Channels in Java
Java
248
star
17

mqperf

Scala
144
star
18

scala-common

Tiny independent libraries with a single purpose, often a single class
Scala
120
star
19

slick-eventsourcing

Example for "Entry level event-sourcing" blog
Scala
118
star
20

lemon-dataset

Lemons quality control dataset
103
star
21

maven-badges

A node.js implementation of https://github.com/jirutka/maven-badges, originally created in ruby.
TypeScript
86
star
22

sbt-softwaremill

A sane set of default build settings
Scala
72
star
23

akka-vs-scalaz

Scala
63
star
24

recursion-training

Recursion schemes training examples and exercises
HTML
59
star
25

livestub

The HTTP server stub you always wanted!
Scala
53
star
26

scala-sql-compare

Scala
50
star
27

stringmask

A micro-library for macro-based case class field masking in .toString
Scala
48
star
28

scala-id-generator

Scala
48
star
29

confluent-playground

Java
44
star
30

sttp-model

Simple Scala HTTP model
Scala
43
star
31

odelay

delayed reactions
Scala
42
star
32

saft

Scala
42
star
33

sttp-openai

Scala
41
star
34

akka-simple-cluster-k8s

Scala
39
star
35

walk-that-type

A tool for evaluating TypeScript types step by step.
TypeScript
39
star
36

softwaremill-common

SoftwareMill Common library
Java
37
star
37

OtterJet

Visualization of messages from a NATS JetStream server
Java
33
star
38

scala-pre-commit-hooks

Pre-commit/Pre-push hooks for Scala
Python
32
star
39

FoXAI

The open-source library for explainable AI. Generic and easy to integrate with PyTorch.
Python
31
star
40

neme-plugin

Scala compiler plugin for turning non exhaustive match warnings into errors
Scala
29
star
41

reactive-event-sourcing-java

Java
28
star
42

zio2-structure

Scala
26
star
43

helisa

Scala API for jenetics
Scala
26
star
44

streams-tests

Scala
25
star
45

meerkat

Observability Starter Kit for JVM Applications
JavaScript
25
star
46

tapir-loom

Scala
24
star
47

sttp-apispec

OpenAPI, AsyncAPI and JSON Schema Scala models.
Scala
23
star
48

node-typescript-starter

A basic boilerplate for node + TypeScript development with debugger source maps support.
TypeScript
22
star
49

free-tagless-compare

Free monads compared to tagless final
Scala
22
star
50

akka-http-session-faq

Java
21
star
51

activator-reactive-kafka-scala

Activator template for Reactive Kafka
Scala
20
star
52

adopt-tapir

A quickstart generator for Tapir projects
Scala
17
star
53

reactive-streams-for-java-developers

Java
17
star
54

scala3-macro-debug

Scala
17
star
55

resilience4s

Scala
16
star
56

react-use-promise-matcher

React hooks allowing you to handle promises in a stateful way
TypeScript
16
star
57

simple-http-server

Simple JVM based HTTP server with no dependencies
Scala
15
star
58

correlator

Scala
15
star
59

detectnet-tests

Python scripts and other resources for tesing DetectNet on Nvidia DIGITS
Python
14
star
60

blockchain-schedule

An experimental collaborative planning app based on Ethereum ("Decentralized Doodle")
TypeScript
14
star
61

blog-scala-structure-lifecycle

Scala
12
star
62

akka-sandbox

Training ground for experiments with Akka framework.
Scala
12
star
63

broadway-pipelines-blog

Constructing effective data processing workflows using Elixir and Broadway
Elixir
12
star
64

undelay

Satisfy Scala Futures quickly
Scala
11
star
65

monix-correlation-id

Scala
10
star
66

cassandra-monitoring

Scripts for the Cassandra Monitoring blog miniseries
10
star
67

reason-companies-example

Reason example application
OCaml
10
star
68

jvmbot

Scala
9
star
69

botarium

A simple starter kit for building bots using Node + TypeScript + BotKit.
TypeScript
8
star
70

sbt-template

Scala
8
star
71

asamal

POC for a CDI-based web lightweight framework
Java
8
star
72

boot-scala-microservice

Bootstrap microservice template that uses micro-deps library https://github.com/4finance/micro-deps
Scala
8
star
73

sttp-shared

Scala
7
star
74

modem-connector

Modulator and Demodulator for HAM Radio AX.25 audio signals
Scala
7
star
75

vehicle-routing-problem-java

Java
6
star
76

idea-pastie-plugin

Plugin to post pastie.org pasties from IntelliJ Idea
Java
5
star
77

trqbox-demo

Ruby
5
star
78

sentinel-cgan

Sentinel generative conditional adversarial network implementation
Python
5
star
79

scalatimes

Pug
5
star
80

tapir-serverless

Scala
5
star
81

scala-compiler-plugin-template

Scala
5
star
82

gatling-zeromq

A Gatling stress test plugin for ZeroMQ protocol
Scala
5
star
83

slack-alphabet

Scala
4
star
84

scalar-conf-website

Scalar - Scala Conference in Central Europe
Python
4
star
85

try-them-off

Showcase service presenting possible usage of the Try monad from Vavr.
Java
4
star
86

sttp-openapi-example

Scala
4
star
87

cache-get-or-create

Java
4
star
88

bootzooka-react

Simple project to quickly start developing a web application using React and Akka HTTP, without the need to write login, user registration etc. https://softwaremill.com/open-source/
Scala
4
star
89

fabrica

Shell
3
star
90

akka-typed-workshop

Scala
3
star
91

kuberenetes-fundamentals

Training projects to explore k8s features
Scala
3
star
92

oauth_tutorial

Phoenix OAuth tutorial
Elixir
3
star
93

terraform-gke-bootstrap

HCL
3
star
94

sttp-native-cli

Scala Native with scala-cli and sttp example
Scala
3
star
95

functional-pancakes

Scala
3
star
96

play-scala-slick-example-part2

Scala
3
star
97

ansible-bigbluebutton

Shell
3
star
98

kleisli-example

Scala
3
star
99

loom-protect

Java
3
star
100

supler-example

Example project for Supler http://supler.io
JavaScript
2
star