Github v3 API: Pithub

15 Jul 2011

Almost one month ago Github released a new version of their API: The Github v3 API. I’ve checked the CPAN and found Net::Github there, which supports v2 and v1 of the API so far. From my understanding, the Net:: modules family should be somehow lightweight, please correct me if I’m wrong. They should not do more than providing an interface to the API, which is exactly what Net::Github does in a very good way. But I was looking for something else, something that does more than this and something that supports the new v3 API. That’s why I wrote Pithub (also available on Github). The API should be almost stable now. There are two kind of test suites included: One is not sending any requests to the Github API at all. It is just verifying that the methods are generating correct HTTP requests. Then there’s the second test suite: It’s sending real requests to the live Github API. It’s covering around 90% of all available API calls, just heading to reach the 100% in the next weeks. Running on the live API can generate a lot of activity in your (and especially your contacts) newsfeed. So if you’re eager to contribute to this project and you want to run the live tests, I highly recommend that you setup a test account for that. By default the live testsuite is disabled, via environment variables.

The absolute maximum of entries, that are returned per API call, is limited to 100 (the default is 30). If you want to list all repositories of a user, who has more than 100 repositories, you need more than one API call for that. Instead of doing this manually, you can tell Pithub to take care of that by using its auto pagination feature:

#!/usr/bin/env perl

use strict;
use warnings;
use Pithub::Repos;

my $r = Pithub::Repos->new(
    per_page        => 100,
    auto_pagination => 1,
);
my $result = $r->list( user => 'rjbs' );

unless ( $result->success ) {
    printf "something is fishy: %s\n", $result->response->status_line;
    exit 1;
}

while ( my $row = $result->next ) {
    printf "%s: %s\n", $row->{name}, $row->{description} || 'no description';
}

Right now in the second I’m writing this blog post, rjbs++ has 318 public repositories. Running the script listed above will make four requests to the Github API:

  • [https://api.github.com/users/rjbs/repos?per_page=100&page=1](https://api.github.com/users/rjbs/repos?per_page=100&page=1)
  • [https://api.github.com/users/rjbs/repos?per_page=100&page=2](https://api.github.com/users/rjbs/repos?per_page=100&page=2)
  • [https://api.github.com/users/rjbs/repos?per_page=100&page=3](https://api.github.com/users/rjbs/repos?per_page=100&page=3)
  • [https://api.github.com/users/rjbs/repos?per_page=100&page=4](https://api.github.com/users/rjbs/repos?per_page=100&page=4)

Probably nobody else except me is going to use this library, because there’s Net::Github already and I bet it’s going to support v3 of the API any time soon as well. Even though it was (and is) just fun for me writing it :). I’ll write some more about it in the coming days/weeks…