Net::GitHub::V3 - Github API v3
Prefer:
use Net::GitHub;
my $gh = Net::GitHub->new(
version => 3,
login => 'fayland', pass => 'mypass',
# or
# access_token => $oauth_token
);
Or:
use Net::GitHub::V3;
my $gh = Net::GitHub::V3->new(
login => 'fayland', pass => 'mypass',
# or
# access_token => $oauth_token
);
<http://developer.github.com/v3/>
Authentication
There are two ways to authenticate through GitHub API v3:
- login/pass
-
my $gh = Net::GitHub::V3->new( login => $ENV{GITHUB_USER}, pass => $ENV{GITHUB_PASS} );
- access_token
-
my $gh = Net::GitHub->new( access_token => $ENV{GITHUB_ACCESS_TOKEN} );
raw_response
my $gh = Net::GitHub->new(
# login/pass or access_token
raw_response => 1
);
return raw HTTP::Response object
raw_string
my $gh = Net::GitHub->new(
# login/pass or access_token
raw_string => 1
);
return HTTP::Response response content as string
api_throttle
my $gh = Net::GitHub->new(
# login/pass or access_token
api_throttle => 0
);
To disable call rate limiting (e.g. if your account is whitelisted), set
api_throttle to 0.
RaiseError
By default, error responses are propagated to the user as they are received from
the API. By switching
RaiseError on you can make the be turned into
exceptions instead, so that you don't have to check for error response after
every call.
Iterating over pages: next_url, last_url, prev_url, first_url, per_page
Any methods which return multiple results
may be paginated. After
performing a query you should check to see if there are more results. These
attributes will be reset for each query.
The predicates to check these attributes are "has_next_page",
"has_last_page", "has_prev_page" and
"has_first_page".
"per_page" defaults to 100. It will be applied to GET urls no matter
it supports or not.
See Github's documentation: <http://developer.github.com/v3/#pagination>
my @issues = $gh->issue->repos_issues;
while ($gh->issue->has_next_page) {
push @issues, $gh->issue->query($gh->issue->next_url);
## OR ##
push @issues, $gh->issue->next_page;
}
Iterating over individual items: next_xxx and close_xxx
The queries which can return paginated results can also be evaluated one by one,
like this:
while (my $issue = $gh->issue->next_repos_issue( @args )) {
# do something with $issue
}
The arguments to next_repos_issue are the same as for repos_issues, and is also
applicable to all other interfaces which offer a next_xxx method. All
available next_xxx methods are listed in the documentation of the
corresponding modules, see the list below.
If you loop over the next_xxx interfaces, new API calls will be performed
automatically, but only when needed to fetch more items. An undefined return
value means there are no more items.
To start over with the first item, you need to close the iteration. Every
next_xxx method has a corresponding close_xxx method which must be called with
exactly the same parameters as the next_xxx method to take effect:
$gh->issue->close_repos_issue(@args);
If you use Net::GitHub::V3 in a command line program, there is no need to call
the close_xxx methods at all. As soon as the Net::GitHub::V3 object $gh goes
out of scope, everything is neatly cleaned up.
However, if you have a long-lived Net::GitHub::V3 object, e.g. in a persistent
service process which provides an own interface to its users and talks to
GitHub under the hood, then it is advisable to close the iterations when
you're done with them.
For brevity and because they usually are not needed, the close_xxx methods are
not listed with their modules. It is guaranteed that
every next_xxx
method has a corresponding close_xxx method.
ua
To set the proxy for ua, you can do something like following
$gh->ua->proxy('https', 'socks://127.0.0.1:9050');
$gh->ua is an instance of LWP::UserAgent
query($method, $url, $data)
my $data = $gh->query('/user');
$gh->query('PATCH', '/user', $data);
$gh->query('DELETE', '/user/emails', [ 'myemail@somewhere.com' ]);
query API directly
next_page
When the results have been paginated, "next_page" is sugar for the
common case of iterating through all the pages in order. It simply calls
"query" with the "next_url".
set_default_user_repo
$gh->set_default_user_repo('fayland', 'perl-net-github'); # take effects for all $gh->
$gh->repos->set_default_user_repo('fayland', 'perl-net-github'); # take effects on $gh->repos
To ease the keyboard, we provided two ways to call any method which starts
with :user/:repo
1. SET user/repos before call methods below
$gh->set_default_user_repo('fayland', 'perl-net-github');
my @contributors = $gh->repos->contributors;
2. If it is just for once, we can pass :user, :repo before any arguments
my @contributors = $repos->contributors($user, $repo);
user
my $user = $gh->user->show('nothingmuch');
$gh->user->update( bio => 'Just Another Perl Programmer' );
Net::GitHub::V3::Users
repos
my @repos = $gh->repos->list;
my $rp = $gh->repos->create( {
"name" => "Hello-World",
"description" => "This is your first repo",
"homepage" => "https://github.com"
} );
Net::GitHub::V3::Repos
issue
my @issues = $gh->issue->issues();
my $issue = $gh->issue->issue($issue_number);
Net::GitHub::V3::Issues
pull_request
my @pulls = $gh->pull_request->pulls();
Net::GitHub::V3::PullRequests
org
my @orgs = $gh->org->orgs;
Net::GitHub::V3::Orgs
git_data
Net::GitHub::V3::GitData
gist
Net::GitHub::V3::Gists
oauth
Net::GitHub::V3::OAuth
event
Net::GitHub::V3::Events
search
Net::GitHub::V3::Search
Pithub
Refer Net::GitHub