Skip to content

Commit

Permalink
Factor docs in README into Wiki
Browse files Browse the repository at this point in the history 
All of these have been moved into the Wiki where they can be more
easily discovered and collaborated on.
  • Loading branch information
@tarcieri
tarcieri committed Feb 14, 2016
1 parent 93d43f1 commit 6434bb5
Showing 1 changed file with 5 additions and 214 deletions.
219 changes: 5 additions & 214 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -106,13 +106,14 @@ require "http"
[Please see the http.rb wiki](https://github.com/httprb/http/wiki)
for more detailed documentation and usage notes.

The following API documentation is also available:

## Basic Usage

Here's some simple examples to get you started:
* [YARD API documentation](http://www.rubydoc.info/gems/http/frames)
* [Chainable module (all chainable methods)](http://www.rubydoc.info/gems/http/HTTP/Chainable)

### Basic Usage

### GET requests
Here's some simple examples to get you started:

```ruby
>> HTTP.get("https://github.com").to_s
Expand Down Expand Up @@ -145,216 +146,6 @@ The response body can be streamed with `HTTP::Response::Body#readpartial`:
In practice you'll want to bind the HTTP::Response::Body to a local variable (e.g.
"body") and call readpartial on it repeatedly until it returns `nil`.


### POST requests

Making POST requests is simple too. Want to POST a form?

```ruby
HTTP.post("http://example.com/resource", :form => {:foo => "42"})
```
Making GET requests with query string parameters is as simple.

```ruby
HTTP.get("http://example.com/resource", :params => {:foo => "bar"})
```

Want to POST with a specific body, JSON for instance?

```ruby
HTTP.post("http://example.com/resource", :json => { :foo => "42" })
```

Or just a plain body?

```ruby
HTTP.post("http://example.com/resource", :body => "foo=42&bar=baz")
```

Posting a file?

``` ruby
HTTP.post("http://examplc.com/resource", :form => {
:username => "ixti",
:avatar => HTTP::FormData::File.new("/home/ixit/avatar.png")
})
```

It's easy!


### Proxy Support

Making request behind proxy is as simple as making them directly. Just specify
hostname (or IP address) of your proxy server and its port, and here you go:

```ruby
HTTP.via("proxy-hostname.local", 8080)
.get("http://example.com/resource")
```

Proxy needs authentication? No problem:

```ruby
HTTP.via("proxy-hostname.local", 8080, "username", "password")
.get("http://example.com/resource")
```


### Adding Headers

The HTTP gem uses the concept of chaining to simplify requests. Let's say
you want to get the latest commit of this library from GitHub in JSON format.
One way we could do this is by tacking a filename on the end of the URL:

```ruby
HTTP.get("https://github.com/httprb/http/commit/HEAD.json")
```

The GitHub API happens to support this approach, but really this is a bit of a
hack that makes it easy for people typing URLs into the address bars of
browsers to perform the act of content negotiation. Since we have access to
the full, raw power of HTTP, we can perform content negotiation the way HTTP
intends us to, by using the Accept header:

```ruby
HTTP.headers(:accept => "application/json")
.get("https://github.com/httprb/http/commit/HEAD")
```

This requests JSON from GitHub. GitHub is smart enough to understand our
request and returns a response with `Content-Type: application/json`.

Shorter alias exists for `HTTP.headers`:

```ruby
HTTP[:accept => "application/json"]
.get("https://github.com/httprb/http/commit/HEAD")
```


### Authorization Header

With [HTTP Basic Authentication](http://tools.ietf.org/html/rfc2617) using
a username and password:

```ruby
HTTP.basic_auth(:user => "user", :pass => "pass")
# <HTTP::Headers {"Authorization"=>"Basic dXNlcjpwYXNz"}>
```

Or with plain as-is value:

```ruby
HTTP.auth("Bearer VGhlIEhUVFAgR2VtLCBST0NLUw")
# <HTTP::Headers {"Authorization"=>"Bearer VGhlIEhUVFAgR2VtLCBST0NLUw"}>
```

And Chain all together!

```ruby
HTTP.basic_auth(:user => "user", :pass => "pass")
.headers("Cookie" => "9wq3w")
.get("https://example.com")
```


### Content Negotiation

As important a concept as content negotiation is to HTTP, it sure should be easy,
right? But usually it's not, and so we end up adding ".json" onto the ends of
our URLs because the existing mechanisms make it too hard. It should be easy:

```ruby
HTTP.accept(:json).get("https://github.com/httprb/http/commit/HEAD")
```

This adds the appropriate Accept header for retrieving a JSON response for the
given resource.


### Reuse HTTP connection: HTTP Keep-Alive

If you need to make many successive requests against the same host,
you can create client with persistent connection to the host:

``` ruby
begin
# create HTTP client with persistent connection to api.icndb.com:
http = HTTP.persistent "http://api.icndb.com"

# issue multiple requests using same connection:
jokes = 100.times.map { http.get("/jokes/random").to_s }
ensure
# close underlying connection when you don't need it anymore
http.close if http
end

```

If the optional code block is given, it will be passed the client with
persistent connection to the host as an argument and `client.close` will be
automatically called when the block terminates.
The value of the block will be returned:

``` ruby
jokes = HTTP.persistent "http://api.icndb.com" do |http|
100.times.map { http.get("/jokes/random").to_s }
end
```

##### NOTICE

You must consume response before sending next request via persistent connection.
That means you need to call `#to_s`, `#parse` or `#flush` on response object.
In the example above we used `http.get("/jokes/random").to_s` to get response
bodies. That works perfectly fine, because `#to_s` reads off the response.

Sometimes you don't need response body, or need whole response object to
access it's status, headers etc instead. You can either call `#to_s` to
make sure response was flushed and then use response object itself, or use
`#flush` (syntax sugar for `#tap(&:to_s)` that will do that for you:


``` ruby
contents = HTTP.persistent "http://en.wikipedia.org" do |http|
%w(Hypertext_Transfer_Protocol Git GitHub Linux Hurd).map do
http.get("/wiki/#{target}").flush
end
end
```


### Timeouts

By default, HTTP does not timeout on a request. You can enable per operation
(each read/write/connect call) or global (sum of all read/write/connect calls).

Per operation timeouts are what `Net::HTTP` and the majority of HTTP clients do:

``` ruby
HTTP.timeout(:per_operation, :write => 2, :connect => 5, :read => 10)
.get "http://example.com"

# For convinience, you can omit timeout type in this case. So following has
# same result as the above:

HTTP.timeout(:write => 2, :connect => 5, :read => 10).get "http://example.com"
```

Global timeouts let you set an upper bound of how long a request can take,
without having to rely on `Timeout.timeout`:

``` ruby
HTTP.timeout(:global, :write => 1, :connect => 1, :read => 1)
.get "http://example.com"
```

Uses a timeout of 3 seconds, for the entire `get` call.

*Warning!* You cannot use Celluloid::IO with timeouts currently.


## Supported Ruby Versions

This library aims to support and is [tested against][travis] the following Ruby
Expand Down

0 comments on commit 6434bb5

Please sign in to comment.