diff options
author | adamw <adam@warski.org> | 2017-07-10 15:18:56 +0200 |
---|---|---|
committer | adamw <adam@warski.org> | 2017-07-10 15:18:56 +0200 |
commit | 74a1d680d5f093ab45b31553bf5f5ccd08d5ae16 (patch) | |
tree | 424a9aa8d4f74e668d7ed999a180c5f3a758c7cc /README.md | |
parent | 63e244227ca9d7824d9ec99b558d5bcedf704136 (diff) | |
download | sttp-74a1d680d5f093ab45b31553bf5f5ccd08d5ae16.tar.gz sttp-74a1d680d5f093ab45b31553bf5f5ccd08d5ae16.tar.bz2 sttp-74a1d680d5f093ab45b31553bf5f5ccd08d5ae16.zip |
URI interpolator readme, more tests
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 43 |
1 files changed, 43 insertions, 0 deletions
@@ -49,6 +49,49 @@ implicit val handler = HttpConnectionSttpHandler Any request definition starts from `sttp`: the empty request. This can be further customised, each time yielding a new, immutable request description (unless a mutable body is set on the request, such as a byte array). +## 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._ +import java.net.URI + +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 + +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 +``` + ## Request types All requests have type `RequestTemplate[U]`, where `U[_]` specifies if the request method and URL are specified. There |