API::Github - Perl 5 API wrapper for Github
version 0.02
use API::Github;
my $github = API::Github->new(
username => 'USERNAME',
token => 'TOKEN',
identifier => 'APPLICATION NAME',
);
$github->debug(1);
$github->fatal(1);
my $user = $github->users('h@x0r');
my $results = $user->fetch;
# after some introspection
$user->update( ... );
This distribution provides an object-oriented thin-client library for interacting with the Github (http://github.com) API. For usage and documentation information visit https://developer.github.com/v3.
A thin-client library is advantageous as it has complete API coverage and can easily adapt to changes in the API with minimal effort. As a thin-client library, this module does not map specific HTTP requests to specific routines, nor does it provide parameter validation, pagination, or other conventions found in typical API client implementations, instead, it simply provides a simple and consistent mechanism for dynamically generating HTTP requests. Additionally, this module has support for debugging and retrying API calls as well as throwing exceptions when 4xx and 5xx server response codes are returned.
my $user = $github->users('h@x0r');
$user->action; # GET /users/h@x0r
$user->action('head'); # HEAD /users/h@x0r
$user->action('patch'); # PATCH /users/h@x0r
Building up an HTTP request object is extremely easy, simply call method names which correspond to the API's path segments in the resource you wish to execute a request against. This module uses autoloading and returns a new instance with each method call. The following is the equivalent:
my $user = $github->resource('users', 'h@x0r');
# or
my $users = $github->users;
my $user = $users->resource('h@x0r');
# then
$user->action('put', %args); # PUT /users/h@x0r
Because each call returns a new API instance configured with a resource locator based on the supplied parameters, reuse and request isolation are made simple, i.e., you will only need to configure the client once in your application.
my $users = $github->users;
# query-string parameters
$users->fetch( query => { ... } );
# equivalent to
my $users = $github->resource('users');
$users->action( get => ( query => { ... } ) );
This example illustrates how you might fetch an API resource.
my $users = $github->users;
# content-body parameters
$users->create( data => { ... } );
# query-string parameters
$users->create( query => { ... } );
# equivalent to
$github->resource('users')->action(
post => ( query => { ... }, data => { ... } )
);
This example illustrates how you might create a new API resource.
my $users = $github->users;
my $user = $users->resource('h@x0r');
# content-body parameters
$user->update( data => { ... } );
# query-string parameters
$user->update( query => { ... } );
# or
my $user = $github->users('h@x0r');
$user->update(...);
# equivalent to
$github->resource('users')->action(
put => ( query => { ... }, data => { ... } )
);
This example illustrates how you might update a new API resource.
my $users = $github->users;
my $user = $users->resource('h@x0r');
# content-body parameters
$user->delete( data => { ... } );
# query-string parameters
$user->delete( query => { ... } );
# or
my $user = $github->users('h@x0r');
$user->delete(...);
# equivalent to
$github->resource('users')->action(
delete => ( query => { ... }, data => { ... } )
);
This example illustrates how you might delete an API resource.
my $users = $github->resource('users', 'h@x0r');
my ($results, $transaction) = $users->action( ... );
my $request = $transaction->req;
my $response = $transaction->res;
my $headers;
$headers = $request->headers;
$headers = $response->headers;
# etc
This example illustrates how you can access the transaction object used represent and process the HTTP transaction.
$github->identifier;
$github->identifier('IDENTIFIER');
The identifier parameter should be set to a string that identifies your application.
$github->token;
$github->token('TOKEN');
The token parameter should be set to the API user's personal access token.
$github->username;
$github->username('USERNAME');
The username parameter should be set to the API user's username.
$github->debug;
$github->debug(1);
The debug attribute if true prints HTTP requests and responses to standard out.
$github->fatal;
$github->fatal(1);
The fatal attribute if true promotes 4xx and 5xx server response codes to exceptions, a API::Github::Exception object.
$github->retries;
$github->retries(10);
The retries attribute determines how many times an HTTP request should be retried if a 4xx or 5xx response is received. This attribute defaults to 0.
$github->timeout;
$github->timeout(5);
The timeout attribute determines how long an HTTP connection should be kept alive. This attribute defaults to 10.
$github->url;
$github->url(Mojo::URL->new('https://api.github.com'));
The url attribute set the base/pre-configured URL object that will be used in all HTTP requests. This attribute expects a Mojo::URL object.
$github->user_agent;
$github->user_agent(Mojo::UserAgent->new);
The user_agent attribute set the pre-configured UserAgent object that will be used in all HTTP requests. This attribute expects a Mojo::UserAgent object.
my $result = $github->action($verb, %args);
# e.g.
$github->action('head', %args); # HEAD request
$github->action('optons', %args); # OPTIONS request
$github->action('patch', %args); # PATCH request
The action method issues a request to the API resource represented by the
object. The first parameter will be used as the HTTP request method. The
arguments, expected to be a list of key/value pairs, will be included in the
request if the key is either data or query.
my $results = $github->create(%args);
# or
$github->POST(%args);
The create method issues a POST request to the API resource represented by
the object. The arguments, expected to be a list of key/value pairs, will be
included in the request if the key is either data or query.
my $results = $github->delete(%args);
# or
$github->DELETE(%args);
The delete method issues a DELETE request to the API resource represented by
the object. The arguments, expected to be a list of key/value pairs, will be
included in the request if the key is either data or query.
my $results = $github->fetch(%args);
# or
$github->GET(%args);
The fetch method issues a GET request to the API resource represented by the
object. The arguments, expected to be a list of key/value pairs, will be
included in the request if the key is either data or query.
my $results = $github->update(%args);
# or
$github->PUT(%args);
The update method issues a PUT request to the API resource represented by
the object. The arguments, expected to be a list of key/value pairs, will be
included in the request if the key is either data or query.
$github->emojis;
The emojis method returns a new instance representative of the API emojis resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/emojis.
$github->events;
The events method returns a new instance representative of the API events resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/activity/events.
$github->feeds;
The feeds method returns a new instance representative of the API feeds resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/activity/feeds.
$github->gists;
The gists method returns a new instance representative of the API gists resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/gists.
$github->gitignore;
The gitignore method returns a new instance representative of the API gitignore resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/gitignore.
$github->issues;
The issues method returns a new instance representative of the API issues resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/issues.
$github->licenses;
The licenses method returns a new instance representative of the API licenses resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/licenses.
$github->markdown;
The markdown method returns a new instance representative of the API markdown resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/markdown.
$github->meta;
The meta method returns a new instance representative of the API meta resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/meta.
$github->notifications;
The notifications method returns a new instance representative of the API notifications resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/activity/notifications.
$github->orgs;
The orgs method returns a new instance representative of the API orgs resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/orgs.
$github->rate_limit;
The rate_limit method returns a new instance representative of the API rate_limit resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/rate_limit.
$github->repos;
The repos method returns a new instance representative of the API repos resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/repos.
$github->search;
The search method returns a new instance representative of the API search resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/search.
$github->users;
The users method returns a new instance representative of the API users resource requested. This method accepts a list of path segments which will be used in the HTTP request. The following documentation can be used to find more information. https://developer.github.com/v3/users.
Al Newkirk anewkirk@ana.io
This software is copyright (c) 2014 by Al Newkirk.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.