Conditional Requests

README.md

@@ -64,6 +64,34 @@ client = Octokit::Client.new(:login => "me", :oauth_token => "oauth2token")
 client.follow("sferik")
 ```
 
+## Rate Limiting and Conditional Requests
+GitHub limits API requests to 5000 per hour.
+
+```ruby
+client = Octokit::Client.new(:login => "me", :oauth_token => "oauth2token")
+client.ratelimit_remaining  # 5000
+client.repositories
+client.ratelimit_remaining  # 4999
+```
+
+You can make conditional requests which will only return data to you if there
+have been changes since your last request. Pass either the `since` or `etag`
+option to any API call to perform a conditional request, and immediately after
+the request is complete the client will have the attributes `last_modified` and
+`etag` populated to be used for the next identical API call.
+
+```ruby
+client = Octokit::Client(:login => "me", :oauth_token => "oauth2token")
+client.ratelimit_remaining                    # 5000
+client.repositories                           # (Returns an array of repositories)
+client.ratelimit_remaining                    # 4999
+repos_last_modified = client.last_modified
+
+client.repositories(nil,
+              :since => repos_last_modified)  # nil
+client.ratelimit_remaining                    # 4999
+```
+
 ## Using with GitHub Enterprise
 
 To use with [GitHub Enterprise](https://enterprise.github.com/), you'll need to

lib/octokit/client.rb

@@ -28,6 +28,7 @@
 module Octokit
   class Client
     attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
+    attr_accessor(:last_modified, :etag)
 
     def initialize(options={})
       options = Octokit.options.merge(options)

lib/octokit/request.rb

@@ -39,6 +39,9 @@ def ratelimit_remaining
     def request(method, path, options, version, authenticate, raw, force_urlencoded)
       path.sub(%r{^/}, '') #leading slash in path fails in github:enterprise
       response = connection(authenticate, raw, version, force_urlencoded).send(method) do |request|
+        request.headers['If-Modified-Since'] = options.delete(:since) unless options[:since].nil?
+        request.headers['If-None-Match'] = options.delete(:etag) unless options[:etag].nil?
+
         case method
         when :delete, :get
           if auto_traversal && per_page.nil?
@@ -58,6 +61,9 @@ def request(method, path, options, version, authenticate, raw, force_urlencoded)
         request.headers['Host'] = Octokit.request_host if Octokit.request_host
       end
 
+      self.last_modified = response.headers['Last-Modified']
+      self.etag = response.headers['ETag'].gsub('"', '') unless response.headers['ETag'].nil?
+
       if raw
         response
       elsif auto_traversal && ( next_url = links(response)["next"] )