From 8a273bf93f55b928b79059a486005d95a3e9f6f8 Mon Sep 17 00:00:00 2001
From: Bryan Goss <bcgoss@users.noreply.github.com>
Date: Thu, 19 Jan 2017 03:23:21 -0700
Subject: [PATCH] Issue #551 Revise Readme to be more accessible (#659)

* Update README.md
---
 README.md | 33 ++++++++++++++++++++++++---------
 1 file changed, 24 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 80264735..4fa92e7e 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,23 @@ Available at [rubydoc.info](http://www.rubydoc.info/gems/faraday).
 
 ## Usage
 
+### Basic Use
+
+```ruby
+response = Faraday.get 'http://sushi.com/nigiri/sake.json'
+```
+A simple `get` request can be performed by using the syntax described above. This works if you don't need to set up anything; you can roll with just the default middleware
+stack and default adapter (see [Faraday::RackBuilder#initialize](https://github.com/lostisland/faraday/blob/master/lib/faraday/rack_builder.rb)).
+
+A more flexible way to use Faraday is to start with a Connection object. If you want to keep the same defaults, you can use this syntax:
+
+```ruby
+conn = Faraday.new(:url => 'http://www.example.com') 
+response = conn.get '/users'                 # GET http://www.example.com/users' 
+```
+
+Connections can also take an options hash as a parameter or be configured by using a block. Checkout the section called [Advanced middleware usage](#advanced-middleware-usage) for more details about how to use this block for configurations. 
+
 ```ruby
 conn = Faraday.new(:url => 'http://sushi.com') do |faraday|
   faraday.request  :url_encoded             # form-encode POST params
@@ -37,7 +54,10 @@ conn = Faraday.new(:url => 'http://sushi.com/api_key=s3cr3t') do |faraday|
     logger.filter(/(api_key=)(\w+)/,'\1[REMOVED]')
   end
 end
+```
+Once you have the connection object, use it to make HTTP requests. You can pass paramters to it in a few different ways:
 
+```ruby
 ## GET ##
 
 response = conn.get '/nigiri/sake.json'     # GET http://sushi.com/nigiri/sake.json
@@ -45,7 +65,7 @@ response.body
 
 conn.get '/nigiri', { :name => 'Maguro' }   # GET http://sushi.com/nigiri?name=Maguro
 
-conn.get do |req|                           # GET http://sushi.com/search?page=2&limit=100
+conn.get do |req|                           # GET http://sushi.com/search?page=2&limit=100  
   req.url '/search', :page => 2
   req.params['limit'] = 100
 end
@@ -53,7 +73,9 @@ end
 ## POST ##
 
 conn.post '/nigiri', { :name => 'Maguro' }  # POST "name=maguro" to http://sushi.com/nigiri
-
+```
+Some configuration options can be adjusted per request:
+```ruby
 # post payload as JSON instead of "www-form-urlencoded" encoding:
 conn.post do |req|
   req.url '/nigiri'
@@ -70,13 +92,6 @@ conn.get do |req|
 end
 ```
 
-If you don't need to set up anything, you can roll with just the default middleware
-stack and default adapter (see [Faraday::RackBuilder#initialize](https://github.com/lostisland/faraday/blob/master/lib/faraday/rack_builder.rb)):
-
-```ruby
-response = Faraday.get 'http://sushi.com/nigiri/sake.json'
-```
-
 ### Changing how parameters are serialized
 
 Sometimes you need to send the same URL parameter multiple times with different