Readme

1 files changed, 50 insertions, 1 deletions

diff --git a/README.md b/README.md
index 64f7925..719ba43 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,16 @@
 
 The HTTP client for Scala that you always wanted
  
+```
+val state = "closed"
+val request = sttp.get(uri"https://api.github.com/repos/adamw/elasticmq/issues?state=$state")
+  
+val response = request.send(responseAsString("utf-8"))
+
+println(response.header("Content-Length")) // has type Option[String]
+println(response.body)                     // has type String
+```
+ 
 ## Goals of the project
 
 * provide a simple, discoverable, no-surprises, reasonably type-safe API for making HTTP requests
@@ -17,10 +27,49 @@ which contain common cookies/headers/options, which can later be specialized usi
 * support for multiple backends, both synchronous and asynchronous, with backend-specific streaming support
 * TODO URI interpolator with optional parameters support
 
+## Usage 
+
+First, make sure to import:
+
+```
+import com.softwaremill.sttp._
+```
+
+To send requests, you will also need a backend. A default, synchronous backend based on Java's `HttpURLConnection`
+is provided out-of-the box. An implicit value needs to be in scope to invoke `send()` (however it's possible to 
+create requests without any implicit backend in scope): 
+
+```
+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).
+
+## Request types
+
+All requests have type `RequestTemplate[U]`, where `U[_]` specifies if the request method and URL are specified. There
+are two type aliases for the request template that are used:
+
+* `type Request = RequestTemplate[Id]`, where `type Id[X] = X` is the identity, meaning that the request has both a 
+method and URI. 
+* `type PartialRequest = RequestTemplate[Empty]`, where `type Empty[X] = None`, meaning that the request has neither
+a method nor an URI. Both of these fields will be set to `None` (the `Option` subtype).
+
+## 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)
+
 ## 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)
\ No newline at end of file
+* [fs2-http](https://github.com/Spinoco/fs2-http)
+* [http4s](http://http4s.org/v0.17/client/)
\ No newline at end of file