GitHubBub
A low level GitHub client that makes the disgusting issue of header based url pagination simple.
What
Seriously? I just told you, see above.
Why
I'm using this in a few places such as http://www.codetriage.com/. Need low level control, without sacrificing usability.
Install
In your Gemfile
gem 'git_hub_bub'
Then run $ bundle install
Upgrading to v1
Version 0.x of this library would raise an exception on any non-200 response. The current version does not do this, it instead provides a method
response = GitHubBub.get("repoZ/railZ/railZ/issueZ")
response.success?
# => false
Note this only checks for 2.x status, it does not acount for any other status codes, best practice is to manually manage yourself
To preserve previous behavior of raising an error on non-200 status. You can set the GIT_HUB_BUB_RAISE_ON_FAIL environment variable to any value.
In v1 the ability to sleep to add a rate limit was added:
response = GitHubBub.get('repos/rails/rails/issues')
response.rate_limit_sleep!
As the number of available requests gets smaller and smaller this will sleep for longer and longer.
GET Whatever you Want:
To make requests to a GET endpoint use GitHubBub.get
response = GitHubBub.get('repos/rails/rails/issues')
Now you can do stuff like grab the json-ified body:
response.json_body # => { foo: "bar" ...}
And get pagination (if there is any):
response.next_url # => "https://api.github.com/repositories/8514/issues?page=2"
response.last_url? # => false
response.pagination # => {"next_url"=>"https://api.github.com/repositories/8514/issues?page=2", "last_url"=>"https://api.github.com/repositories/8514/issues?page=18"}
response.rate_limit_remaining # => 60
Passing Params
To pass parameters such as page number, or sorting or whatever, input a hash as the second argument.
GitHubBub.get('repositories/8514/issues', page: 1, sort: 'comments', direction:'desc')
Passing Anything Else
Anything else you pass in the third argument will be given to Excon which powers GitHubBub. So if you want to set headers you can do it like this:
GitHubBub.get('repositories/8514/issues', {page: 1}, {headers: { "Content-Type" => "application/x-www-form-urlencoded" }})
or
GitHubBub.get('repositories/8514/issues', {}, {headers: { "Content-Type" => "application/x-www-form-urlencoded" }})
See Excon for documentation on more available options.
Default Headers
Default headers are set in GitHubBub::Request
BASE_HEADERS = {'Accept' => "application/#{GITHUB_VERSION}", "User-Agent" => USER_AGENT}
You can change GitHubBub::Request::GITHUB_VERSION and GitHubBub::Request::USER_AGENT.
If you want any other default headers you can set them in EXTRA_HEADERS like so:
GitHubBub::Request::EXTRA_HEADERS = { "Content-Type" => "application/x-www-form-urlencoded" }
Keep in mind this will change them for every request. If you need logic behind your default headers, consider adding a before_send_callback to conditionally modify headers
Authenticated Requests
Some GitHub endpoints require a user's authorization you can do that by passing in token:
GitHubBub.get('/user', token: 'a38ck38ckgoldfishtoken')
Or you can manually set a header like so:
GitHubBub.get('/user', {} {headers: {"Authorization" => "token a38ck38ckgoldfishtoken"}})
You will need to use one of these every time the GitHub api says "as an authenticated user".
Rate limiting
GitHub requests are rate limited. With every request they send back information with the number of requests left and when the time window resets.
Instead of worrying about either of those direct measurements you can instead use this helper method:
response = GitHubBub.get('repos/rails/rails/issues')
response.rate_limit_sleep!
If you are repetitively calling the API you should use this method in each loop to prevent going over your bucket.
As your remaining request limit gets lower this method will sleep for incrementally longer time periods until your limit bucket is refilled. Since this behavior comes after a request it is possible that this request was rate limited. GitHub will return a 403 when you are over your limit.
Callbacks
If you want to mess with the url or options before sending a request you can set a callback globally
GitHubBub::Request.set_before_callback do |request|
request.url = "http://schneems.com"
request. = {do: "anything you want to _all_ the requests" }
end
Endpoints
Check GitHub Developer Docs. When you see something like
GET /users/:user/repos
It means you need to use the GitHubBub.get method and pass in a string like '/users/schneems/repos' the full request might look like this:
GitHubBub.get('/users/schneems/repos')
Other HTTP Methods
Supports everything GitHub currently supports http://developer.github.com/v3/#http-verbs :
HEAD # => GitHubBub.head
GET # => GitHubBub.get
POST # => GitHubBub.post
PATCH # => GitHubBub.patch
PUT # => GitHubBub.put
DELETE # => GitHubBub.delete
Configuration
You can use callbacks and there are some constants you can set, look in GitHubBub::Request. You will definetly want to set GitHubBub::Request::USER_AGENT It needs to be unique to your app: (http://developer.github.com/v3/#user-agent-required).
GitHubBub::Request::USER_AGENT = 'a-unique-and-permanent-agent-to-my-app'
Testing
This gem is tested using the super cool request recording/stubbing framework VCR. This does mean at one point and time all tests ran successfully against GitHub's servers. This also means if you want to write any tests any that are not already recorded will need to hit GitHub servers. So make sure the tests you write don't do anything really bad.
You'll also need a valid .env file
$ cp .sample.env .env
Anything you put in this file will be sourced into your environment for tests. Here is an example .env file.
GITHUB_API_KEY=asdfe92fakeKey43ad638e35asdfd98167847248a26
OWNER=schneems
REPO=wicked
USER_NAME="Richard Schneeman"
WATCH_OWNER=emberjs
WATCH_REPO=ember.js
You will need to change most of these values
GITHUB_API_KEY=asdfe92fakeKey43ad638e35asdfd98167847248a26
Your github API key, you can get one from https://github.com/settings/applications.
OWNER=schneems
Your public github username
REPO=wicked
A repo that you have commit access too.
USER_NAME="Richard Schneeman"
Your real name
WATCH_OWNER=emberjs
The :owner of a repo you might watch or want to watch, needs to be combined with WATCH_REPO. This should be different from OWNER
WATCH_REPO=ember.js
A repo that the WATCH_OWNER owns. Should be different from REPO
License
MIT