1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
|
# sttp
[![Join the chat at https://gitter.im/softwaremill/sttp](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/softwaremill/sttp?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Build Status](https://travis-ci.org/softwaremill/sttp.svg?branch=master)](https://travis-ci.org/softwaremill/sttp)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.softwaremill.sttp/core_2.12/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.softwaremill.sttp/core_2.12)
[![Dependencies](https://app.updateimpact.com/badge/634276070333485056/sttp.svg?config=compile)](https://app.updateimpact.com/latest/634276070333485056/sttp)
The HTTP client for Scala that you always wanted!
```scala
import com.softwaremill.sttp._
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 = sttp.get(uri"https://api.github.com/search/repositories?q=$query&sort=$sort")
implicit val handler = HttpURLConnectionSttpHandler
val response = request.send()
// response.header(...): Option[String]
println(response.header("Content-Length"))
// response.body: by default read into a String
println(response.body)
```
## Goals of the project
* provide a simple, discoverable, no-surprises, reasonably type-safe API for
making HTTP requests and reading responses
* separate definition of a request from request execution
* provide immutable, easily modifiable data structures for requests and
responses
* support multiple execution backends, both synchronous and asynchronous
* provide support for backend-specific request/response streaming
* minimum dependencies
See also the [introduction to sttp](https://softwaremill.com/introducing-sttp-the-scala-http-client)
and [sttp streaming & URI interpolators](https://softwaremill.com/sttp-streaming-uri-interpolator)
blogs.
## How is sttp different from other libraries?
* immutable request builder which doesn't impose any order in which request
parameters need to be specified. Such an approach allows defining partial
requests with common cookies/headers/options, which can later be specialized
using a specific URI and HTTP method.
* support for multiple backends, both synchronous and asynchronous, with
backend-specific streaming support
* URI interpolator with context-aware escaping, optional parameters support
and parameter collections
## Quickstart with Ammonite
If you are an [Ammonite](http://ammonite.io) user, you can quickly start
experimenting with sttp by copy-pasting the following:
```scala
import $ivy.`com.softwaremill.sttp::core:0.0.4`
import com.softwaremill.sttp._
implicit val handler = HttpURLConnectionSttpHandler
sttp.get(uri"http://httpbin.org/ip").send()
```
## Adding sttp to your project
SBT dependency:
```scala
"com.softwaremill.sttp" %% "core" % "0.0.4"
```
`sttp` is available for Scala 2.11 and 2.12, and requires Java 8. The core
module has no transitive dependencies.
If you'd like to use an alternate backend, [see below](#supported-backends)
for additional instructions.
## API
First, import:
```scala
import com.softwaremill.sttp._
```
This brings into scope `sttp`, the starting request (it's an empty request
with the `Accept-Encoding: gzip, defalte` header added). This request can
be customised, each time yielding a new, immutable request description
(unless a mutable body is set on the request, such as a byte array).
For example, we can set a cookie, string-body and specify that this should
be a `POST` request to a given URI:
```scala
val request = sttp
.cookie("login", "me")
.body("This is a test")
.post(uri"http://endpoint.com/secret")
```
The request parameters (headers, cookies, body etc.) can be specified in any
order. There's a lot of ways in which you can customize a request: just
explore the API. And [more will be added](#todo)!
You can create a request description without knowing how it will be sent.
But to send a request, you will need a backend. A default, synchronous backend
based on Java's `HttpURLConnection` is provided out-of-the box. An implicit
value of type `SttpHandler` needs to be in scope to invoke the `send()` on the
request:
```scala
implicit val handler = HttpURLConnectionSttpHandler
val response: Response[String] = request.send()
```
By default the response body is read into a utf-8 string. How the response body
is handled is also part of the request description. The body can be ignore
(`.response(ignore)`), read into a sequence of parameters
(`.response(asParams)`), mapped (`.mapResponse`) and more; some backends also
support request & response streaming.
The default handler doesn't wrap the response into any container, but other
asynchronous handlers might do so. The type parameter in the `Response[_]`
type specifies the type of the body.
## URI interpolator
Using the URI interpolator it's possible to conveniently create `java.net.URI`
instances, which can then be used to specify request endpoints, for example:
```scala
import com.softwaremill.sttp._
val user = "Mary Smith"
val filter = "programming languages"
val endpoint: Uri = uri"http://example.com/$user/skills?filter=$filter"
```
Any values embedded in the URI will be URL-encoded, taking into account the
context (e.g., the whitespace in `user` will be %-encoded as `%20D`, while the
whitespace in `filter` will be query-encoded as `+`).
The possibilities of the interpolator don't end here. Other supported features:
* parameters can have optional values: if the value of a parameter is `None`,
it will be removed
* maps, sequences of tuples and sequences of values can be embedded in the query
part. They will be expanded into query parameters. Maps and sequences of tuples
can also contain optional values, for which mappings will be removed
if `None`.
* optional values in the host part will be expanded to a subdomain if `Some`,
removed if `None`
* sequences in the host part will be expanded to a subdomain sequence
* if a string contains the protocol is embedded *as the first element*, it will
not be escaped, allowing to embed entire addresses as prefixes, e.g.:
`uri"$endpoint/login"`, where `val endpoint = "http://example.com/api"`.
A fully-featured example:
```scala
import com.softwaremill.sttp._
val secure = true
val scheme = if (secure) "https" else "http"
val subdomains = List("sub1", "sub2")
val vx = Some("y z")
val params = Map("a" -> 1, "b" -> 2)
val jumpTo = Some("section2")
uri"$scheme://$subdomains.example.com?x=$vx&$params#$jumpTo"
// generates:
// https://sub1.sub2.example.com?x=y+z&a=1&b=2#section2
```
## Supported backends
### Summary
| Class | Result wrapper | Supported stream type |
| --- | --- | --- |
| `HttpURLConnectionSttpHandler` | None (`Id`) | - |
| `AkkaHttpSttpHandler` | `scala.concurrent.Future` | `akka.stream.scaladsl.Source[ByteString, Any]` |
| `FutureAsyncHttpClientHandler` | `scala.concurrent.Future` | - |
| `ScalazAsyncHttpClientHandler` | `scalaz.concurrent.Task` | - |
| `MonixAsyncHttpClientHandler` | `monix.eval.Task` | `monix.reactive.Observable[ByteBuffer]` |
| `OkHttpSyncClientHandler` | None (`Id`) | - |
| `OkHttpFutureClientHandler` | `scala.concurrent.Future` | - |
### `HttpURLConnectionSttpHandler`
The default **synchronous** handler. Sending a request returns a response wrapped
in the identity type constructor, which is equivalent to no wrapper at all.
To use, add an implicit value:
```scala
implicit val sttpHandler = HttpURLConnectionSttpHandler
```
### `AkkaHttpSttpHandler`
To use, add the following dependency to your project:
```scala
"com.softwaremill.sttp" %% "akka-http-handler" % "0.0.4"
```
This handler depends on [akka-http](http://doc.akka.io/docs/akka-http/current/scala/http/).
A fully **asynchronous** handler. Sending a request returns a response wrapped
in a `Future`.
Next you'll need to add an implicit value:
```scala
implicit val sttpHandler = AkkaHttpSttpHandler()
// or, if you'd like to use an existing actor system:
implicit val sttpHandler = AkkaHttpSttpHandler.usingActorSystem(actorSystem)
```
This backend supports sending and receiving
[akka-streams](http://doc.akka.io/docs/akka/current/scala/stream/index.html)
streams of type `akka.stream.scaladsl.Source[ByteString, Any]`.
To set the request body as a stream:
```scala
import com.softwaremill.sttp._
import com.softwaremill.sttp.akkahttp._
import akka.stream.scaladsl.Source
import akka.util.ByteString
val source: Source[ByteString, Any] = ...
sttp
.streamBody(source)
.post(uri"...")
```
To receive the response body as a stream:
```scala
import com.softwaremill.sttp._
import com.softwaremill.sttp.akkahttp._
import akka.stream.scaladsl.Source
import akka.util.ByteString
implicit val sttpHandler = AkkaHttpSttpHandler()
val response: Future[Response[Source[ByteString, Any]]] =
sttp
.post(uri"...")
.response(asStream[Source[ByteString, Any]])
.send()
```
### `AsyncHttpClientHandler`
To use, add the following dependency to your project:
```scala
"com.softwaremill.sttp" %% "async-http-client-handler-future" % "0.0.4"
// or
"com.softwaremill.sttp" %% "async-http-client-handler-scalaz" % "0.0.4"
// or
"com.softwaremill.sttp" %% "async-http-client-handler-monix" % "0.0.4"
```
This handler depends on [async-http-client](https://github.com/AsyncHttpClient/async-http-client).
A fully **asynchronous** handler, which uses [Netty](http://netty.io) behind the
scenes.
The responses are wrapped depending on the dependency chosen in either a:
* standard Scala `Future`
* [Scalaz](https://github.com/scalaz/scalaz) `Task`. There's a transitive
dependency on `scalaz-concurrent`.
* [Monix](https://monix.io) `Task`. There's a transitive dependency on
`monix-eval`.
Next you'll need to add an implicit value:
```scala
implicit val sttpHandler = FutureAsyncHttpClientHandler()
// or, if you're using the scalaz version:
implicit val sttpHandler = ScalazAsyncHttpClientHandler()
// or, if you're using the monix version:
implicit val sttpHandler = MonixAsyncHttpClientHandler()
// or, if you'd like to use custom configuration:
implicit val sttpHandler = FutureAsyncHttpClientHandler.usingConfig(asyncHttpClientConfig)
// or, if you'd like to instantiate the AsyncHttpClient yourself:
implicit val sttpHandler = FutureAsyncHttpClientHandler.usingClient(asyncHttpClient)
```
#### Streaming using Monix
Currently, only the Monix handler supports streaming (as both Monix and Async
Http Client support reactive streams `Publisher`s out of the box). The type of
supported streams in this case is `Observable[ByteBuffer]`. That is, you can
set such an observable as a request body:
```scala
import com.softwaremill.sttp._
import java.nio.ByteBuffer
import monix.reactive.Observable
val obs: Observable[ByteBuffer] = ...
sttp
.streamBody(obs)
.post(uri"...")
```
And receive responses as an observable stream:
```scala
import com.softwaremill.sttp._
import com.softwaremill.sttp.asynchttpclient.monix._
import java.nio.ByteBuffer
import monix.eval.Task
import monix.reactive.Observable
implicit val sttpHandler = MonixAsyncHttpClientHandler()
val response: Task[Response[Observable[ByteBuffer]]] =
sttp
.post(uri"...")
.response(asStream[Observable[ByteBuffer]])
.send()
```
### `OkHttpClientHandler`
To use, add the following dependency to your project:
```scala
"com.softwaremill.sttp" %% "okhttp-client-handler" % "0.0.4"
```
This handler depends on [OkHttp](http://square.github.io/okhttp/), and offers
both a **synchronous** (`OkHttpSyncClientHandler`) and **asynchronous**
(`OkHttpFutureClientHandler`), `Future`-based handlers.
OkHttp fully supports HTTP/2.
### Custom backends, logging, metrics
It is also entirely possible to write your own backend (if so, please consider
contributing!) or wrapping an existing one. You can even write completely
generic wrappers for any delegate backend, as the each backend comes equipped
with a monad for the response wrapper.
This brings the possibility to `map` and `flatMap` over responses. That way you
could implement e.g. a logging or metric-capturing wrapper.
## Request type
All request descriptions have type `RequestT[U, T, S]` (T as in Template).
If this looks a bit complex, don't worry, what the three type parameters stand
for is the only thing you'll hopefully have to remember when using the API!
Going one-by-one:
* `U[_]` specifies if the request method and URL are specified. Using the API,
this can be either `type Empty[X] = None`, meaning that the request has neither
a method nor an URI. Or, it can be `type Id[X] = X` (type-level identity),
meaning that the request has both a method and an URI specified. Only requests
with a specified URI & method can be sent.
* `T` specifies the type to which the response will be read. By default, this
is `String`. But it can also be e.g. `Array[Byte]` or `Unit`, if the response
should be ignored. Response body handling can be changed by calling the
`.response` method. With backends which support streaming, this can also be
a supported stream type.
* `S` specifies the stream type that this request uses. Most of the time this
will be `Nothing`, meaning that this request does not send a streaming body
or receive a streaming response. So most of the times you can just ignore
that parameter. But, if you are using a streaming backend and want to
send/receive a stream, the `.streamBody` or `response(asStream[S])` will change
the type parameter.
There are two type aliases for the request template that are used:
* `type Request[T, S] = RequestT[Id, T, S]`. A sendable request.
* `type PartialRequest[T, S] = RequestT[Empty, T, S]`
## Notes
* the encoding for `String`s defaults to `utf-8`.
* unless explicitly specified, the `Content-Type` defaults to:
* `text/plain` for text
* `application/x-www-form-urlencoded` for form data
* `multipart/form-data` for multipart form data
* `application/octet-stream` for everything else (binary)
## TODO
* multi-part uploads
* scalaz/fs2 streaming
* proxy support
* connection options, SSL
* *your API improvement idea here*
## Other Scala HTTP clients
* [scalaj](https://github.com/scalaj/scalaj-http)
* [akka-http client](http://doc.akka.io/docs/akka-http/current/scala/http/client-side/index.html)
* [dispatch](http://dispatch.databinder.net/Dispatch.html)
* [play ws](https://github.com/playframework/play-ws)
* [fs2-http](https://github.com/Spinoco/fs2-http)
* [http4s](http://http4s.org/v0.17/client/)
* [Gigahorse](http://eed3si9n.com/gigahorse/)
* [RösHTTP](https://github.com/hmil/RosHTTP)
## Contributing
Take a look at the [open issues](https://github.com/softwaremill/sttp/issues)
and pick a task you'd like to work on!
## Credits
* [Tomasz Szymański](https://github.com/szimano)
* [Adam Warski](https://github.com/adamw)
* [Omar Alejandro Mainegra Sarduy](https://github.com/omainegra)
|