File Coverage

blib/lib/Net/CronIO.pm

Criterion	Covered	Total	%
statement	7	9	77.7
branch			n/a
condition			n/a
subroutine	3	3	100.0
pod			n/a
total	10	12	83.3

use strict;
use warnings;
package Net::CronIO;
{
  $Net::CronIO::VERSION = '0.01';
}

# ABSTRACT: Perl binding for cron.io

use Net::HTTP::API;
use Carp qw(croak);


net_api_declare cronio => (
    api_base_url    => 'http://api.cron.io/v1',
    api_format      => 'json',
    api_format_mode => 'content-type',
    authentication  => 1,
);


net_api_method create_user => (
    description => "Sign up for service and get a username/password",
    method => "POST",
    path => '/users',
    params => [qw(email username password)],
    required => [qw(email username password)],
    expected => [qw(201)],
);


net_api_method get_all_crons => (
    description => "List all the crons you have. Requires authentication.",
    method => "GET",
    path => '/crons',
    authentication => 1,
);


net_api_method create_cron => (
    description => "Create a new cron entry for your account. Requires authentication.",
    method => "POST",
    path => '/crons',
    params => [qw(name url schedule)],
    required => [qw(name url schedule)],
    authentication => 1,
);


net_api_method get_cron => (
    description => "List a specific cron entry. Requires a cron id and authentication.",
    method => "GET",
    path => '/crons/:id',
    params => [qw(id)],
    required => [qw(id)],
    authentication => 1,
);


net_api_method update_cron => (
    description => "Update a cron entry. Requires cron id and authentication.",
    method => "PUT",
    path => '/crons/:id',
    params => [qw(id name url schedule)],
    required => [qw(id)],
    authentication => 1,
);


net_api_method delete_cron => (
    descripton => "Delete a cron entry. Requires cron id and authentication.",
    method => "DELETE",
    path => '/crons/:id',
    params => [qw(id)],
    required => [qw(id)],
    expected => [qw(204)],
    authentication => 1,
);

around 'delete_cron' => sub {
    my $orig = shift;
    my $self = shift;

    my ($content, $response) = $self->$orig(@_);

    if ( $response->is_success ) {
        return 1;
    }
    else {
        croak $response->status_line;
    }
};

around 'create_user' => sub {
    my $orig = shift;
    my $self = shift;

    my ($content, $response) = $self->$orig(@_);

    if ( $response->is_success ) {
        return $content->{'message'};
    }
    else {
        croak $response->status_line . ": " . $response->content;
    }
};

1;


__END__
=pod

=head1 NAME

Net::CronIO - Perl binding for cron.io

=head1 VERSION

version 0.01

=head1 SYNOPSIS

  use 5.014;
  use Net::CronIO;

  my $cron = Net::CronIO->new(
      api_username => 'example',
      api_password => 'sekrit',
  );

  my $newjob = $cron->create_cron(
      name => 'Daily clean up job',
      url => 'http://example.com/blahblah/?cleanup=1',
      schedule => '46 0 * * *',
  );

  my $jobs = $cron->get_all_crons();

  foreach my $job ( $jobs ) {
      if ( $job->{'url'} =~ /deadhost.com/ ) {
          $cron->update_cron(
            id => $job->{'id'},
            url => $job->{'url'} =~ s/deadhost\.com/example\.com/r,
          );
      }
  }

  say "deleted" if ( $cron->delete_cron( id => $jobs->[0]->{'id'} ) );

This is a Perl binding for the L<cron.io|http://cron.io> service.  Cron is a Unix service which
executes jobs on a periodic basis. The cron.io service contacts URLs using the same
time period specification.

At the moment, the only way to generate a username and password for the service is by making
a call on the C<create_user()> method.  Email verification is required before the
credentials are valid.

=head1 ATTRIBUTES

=head2 api_username

You must supply an C<api_username> for every method except C<create_user()>.  This can be done at
object construction time, or later by calling the C<api_username()> method.

=head2 api_password

You must supply an C<api_password> for every method except C<create_user()>.  This can be done at
object construction time, or later by calling the C<api_username()> method.

=head1 METHODS

=head2 create_user()

This method requires the following parameters: C<email>, C<username>, C<password>. This call will register
a username/password with the service.  Human intervention (in the form of an email verification) is required
before your username/password are activated.

Once these credentials are active, you must provide them to this binding to execute other methods.

The return value is a string message provided by the API service (which evaluates to
a true value in Perl.)  This method dies on errors.

=head2 get_all_crons()

This method returns an arrayref containing hashes of all cron jobs for your username.

Hashes will contain the following keys:

=over

=item * C<id>

This is an internal ID used by the service to identify a specific cron job.  It is a required
parameter for most of the other methods.

=item * C<name>

This is the name you assigned to a specific job.

=item * C<url>

The URL to contact at the given schedule specification.

=item * C<schedule>

This is a standard Unix cron style specification.  See L<cron|http://en.wikipedia.com/wiki/Cron> on Wikipedia
for a verbose description of this format.

=back

It is possible this call will return a reference to an empty list.

=head2 create_cron()

This method creates a new job.  Required parameters are C<name>, C<url>, C<schedule>.

The return value is a hash of C<id>, plus the three params you provided.

=head2 get_cron()

This method retrieves a specific job by its C<id>.  C<id> is a required parameter for this
method.  The return value is a hash as described above.

=head2 update_cron()

This method changes values with jobs which already have ids. C<id> is a required parameter.
Optional parameters are any or all of C<name>, C<url>, and/or C<schedule>.

=head2 delete_cron()

This method removes a job from the service. C<id> is a required parameter.  On success, this
method returns a true value.  It dies on errors.

=head1 TESTING NOTE

To execute the full test suite, you must set CRONIO_API_USERNAME and CRONIO_API_PASSWORD environment
variables with valid credentials.

=head1 AUTHOR

Mark Allen <[e-mail]>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Mark Allen.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut