update README.md with example usage

README.md

@@ -2,27 +2,74 @@
 Thin layer to take care of your http requests working with NSURLSession. 
 Taking care of: 
 
-* Json serializer,
-* Multipart upload, 
-* Pluggable object serialization.
+* Json serializer
+* Multipart upload
+* HTTP Basic/Digest authentication support
+* Pluggable object serialization
 
 100% Swift.
 
 ## Example Usage
 
-This example is extracted from AeroGearSample.playground
+To perform an HTTP request use the convenient methods found in the Http object. Here is an example usage:
+
+```swift
+let http = Http("http://server.com")
+
+http.GET("/get", completionHandler: {(response, error) in
+     // handle response
+})
+
+http.POST("/post",  parameters: ["key": "value"], completionHandler: {(response, error) in
+     // handle response
+})
+...
+```
+
+### Authentication
+
+The library also leverages the build-in foundation support for http/digest authentication and exposes a convenient interface by allowing the credential object to be passed on the request. Here is an example
+
 ```swift
-var url = "http://api.icndb.com/jokes"
-var http = Session(url: url, sessionConfig: NSURLSessionConfiguration.defaultSessionConfiguration())
-http.GET(success: {(response: AnyObject?) in
-    if let unwrappedResponse = response as? Dictionary<String, AnyObject> {
-        println("Success: \(unwrappedResponse)")
-    }
-    }, failure: {(error: NSError) in
-        println("Error")
-})// log error
+let credential = NSURLCredential(user: "john", password: "pass", persistence: .None)
+
+http.GET("/protected/endpoint", credential: credential, completionHandler: {(response, error) in
+   // handle response
+})
+```
+
+ You can also set a credential per protection space, so it's automatically picked up once http challenge is requested by the server, thus omitting the need to pass the credential on each request. In this case, you must initialize the ```Http``` object with a custom session configuration object, that has it's credential storage initialized with your credentials:
+
+ ```swift
+// create a protection space
+var protectionSpace: NSURLProtectionSpace = NSURLProtectionSpace(host: "httpbin.org", port: 80,`protocol`: NSURLProtectionSpaceHTTP, realm: "me@kennethreitz.com", authenticationMethod: NSURLAuthenticationMethodHTTPDigest);
+
+// setup credential
+// notice that we use '.ForSession' type otherwise credential storage will discard and
+// won't save it when doing 'credentialStorage.setDefaultCredential' later on
+let credential = NSURLCredential(user: user, password: password, persistence: .ForSession)
+
+// assign it to credential storage
+var credentialStorage: NSURLCredentialStorage = NSURLCredentialStorage.sharedCredentialStorage()
+credentialStorage.setDefaultCredential(credential, forProtectionSpace: protectionSpace);
+
+// set up default configuration and assign credential storage
+var configuration = NSURLSessionConfiguration.defaultSessionConfiguration()
+configuration.URLCredentialStorage = credentialStorage
+
+// assign custom configuration to Http
+var http = Http(baseURL: "http://httpbin.org", sessionConfig: configuration)
+
+http.GET("/protected/endpoint", completionHandler: {(response, error) in
+   // handle response
 })
 ```
+
+### OAuth2 Protocol Support
+
+To support the OAuth2 protocol, we have created a separate library [aerogear-ios-oauth2](https://github.com/aerogear/aerogear-ios-oauth2) that can be easily integrated, in order to provide  out-of-the-box support for communicated with OAuth2 protected endpoints. Please have a look at the "Http and OAuth2Module" section on our [documentation page](http://aerogear.org/docs/guides/aerogear-ios-2.X/Authorization/) for more information. 
+
+
 Do you want to try it on your end? Follow next section steps.
 
 > **NOTE:**  The library has been tested with Xcode 6.1.1