• Stars
    star
    1,418
  • Rank 32,272 (Top 0.7 %)
  • Language
    Scala
  • License
    Apache License 2.0
  • Created almost 7 years ago
  • Updated about 1 month 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,379
star
2

tapir

Declarative, type-safe web endpoints library
Scala
1,294
star
3

macwire

Lightweight and Nonintrusive Scala Dependency Injection Library
Scala
1,252
star
4

quicklens

Modify deeply nested case class fields
Scala
810
star
5

magnolia

Easy, fast, transparent generic derivation of typeclass instances
Scala
745
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

it-cfp-list

List of Call For Papers for IT conferences
374
star
10

retry

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

diffx

Pretty diffs for scala case classes
Scala
343
star
12

kmq

Kafka-based message queue
Scala
320
star
13

scala-clippy

Good advice for Scala compiler errors
Scala
315
star
14

ox

Safe direct style concurrency and resiliency for Scala on the JVM
Scala
305
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
149
star
17

mqperf

Scala
143
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
99
star
21

maven-badges

A node.js implementation of https://github.com/jirutka/maven-badges, originally created in ruby.
TypeScript
85
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
51
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

odelay

delayed reactions
Scala
42
star
31

sttp-model

Simple Scala HTTP model
Scala
42
star
32

saft

Scala
41
star
33

akka-simple-cluster-k8s

Scala
39
star
34

softwaremill-common

SoftwareMill Common library
Java
37
star
35

sttp-openai

Scala
34
star
36

walk-that-type

A tool for evaluating TypeScript types step by step.
TypeScript
31
star
37

FoXAI

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

neme-plugin

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

scala-pre-commit-hooks

Pre-commit/Pre-push hooks for Scala
Python
29
star
40

zio2-structure

Scala
26
star
41

helisa

Scala API for jenetics
Scala
26
star
42

reactive-event-sourcing-java

Java
26
star
43

streams-tests

Scala
25
star
44

tapir-loom

Scala
24
star
45

free-tagless-compare

Free monads compared to tagless final
Scala
22
star
46

node-typescript-starter

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

akka-http-session-faq

Java
21
star
48

sttp-apispec

OpenAPI, AsyncAPI and JSON Schema Scala models.
Scala
21
star
49

activator-reactive-kafka-scala

Activator template for Reactive Kafka
Scala
20
star
50

scala3-macro-debug

Scala
17
star
51

reactive-streams-for-java-developers

Java
17
star
52

resilience4s

Scala
16
star
53

react-use-promise-matcher

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

adopt-tapir

A quickstart generator for Tapir projects
Scala
15
star
55

simple-http-server

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

correlator

Scala
15
star
57

detectnet-tests

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

blockchain-schedule

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

blog-scala-structure-lifecycle

Scala
12
star
60

akka-sandbox

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

broadway-pipelines-blog

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

undelay

Satisfy Scala Futures quickly
Scala
11
star
63

monix-correlation-id

Scala
10
star
64

cassandra-monitoring

Scripts for the Cassandra Monitoring blog miniseries
10
star
65

reason-companies-example

Reason example application
OCaml
10
star
66

jvmbot

Scala
9
star
67

meerkat

Bootzooka, but for observability
JavaScript
9
star
68

botarium

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

sbt-template

Scala
8
star
70

asamal

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

boot-scala-microservice

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

sttp-shared

Scala
7
star
73

modem-connector

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

gatling-zeromq

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

trqbox-demo

Ruby
5
star
76

idea-pastie-plugin

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

sentinel-cgan

Sentinel generative conditional adversarial network implementation
Python
5
star
78

scalatimes

Pug
5
star
79

scala-compiler-plugin-template

Scala
5
star
80

tapir-serverless

Scala
5
star
81

OtterJet

Java
5
star
82

slack-alphabet

Scala
4
star
83

scalar-conf-website

Scalar - Scala Conference in Central Europe
Python
4
star
84

try-them-off

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

sttp-openapi-example

Scala
4
star
86

cache-get-or-create

Java
4
star
87

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
88

vehicle-routing-problem-java

Java
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

play-scala-slick-example-part2

Scala
3
star
93

ansible-bigbluebutton

Shell
3
star
94

kleisli-example

Scala
3
star
95

loom-protect

Java
3
star
96

supler-example

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

jekyll-softwaremill

SoftwareMill.com website written in Jekyll
PHP
2
star
98

demo-spring-boot-docker-compose

Demo application with comparison of spring-boot-docker-compose to testcontainers
Java
2
star
99

oauth_tutorial

Phoenix OAuth tutorial
Elixir
2
star
100

terraform-gke-bootstrap

HCL
2
star