NAME

WebService::CloudFlare::Host - A client API For Hosting Partners

VERSION

000100 (0.1.0)

SYNOPSIS

my $CloudFlare = WebService::CloudFlare::Host->new(
    host_key => 'cloudflare hostkey',
    timeout  => 30,
);

my $response = eval { $CloudFlare->call('UserCreate',
    email => 'richard.castle@hyperionbooks.com',
    pass  => 'ttekceBetaK',
) };

if ( $@ ) {
    die "Error: in " . $@->function . ": " . $@->message;
}


printf("Got API Keys: User Key: %s, User API Key: %s",
    $response->user_key, $response->api_key
);

DESCRIPTION

WebService::CloudFlare::Host is a client side API library to make using CloudFlare simple for hosting providers.

It gives a simple interface for making API calls, getting response objects, and implementing additional API calls.

All API calls have a Request and Response object that define the accepted information for that call.

METHODS

The only method used is call($api_call, %arguments).

When making an API call, the first argument defines the API request to load. This is loaded from Request::. Additional arguments are passed as-is to the Request Object.

Once the object has been made, an HTTP call to the CloudFlare API is made. The JSON returned is used to construct a Response object loaded from Response:: with the same name as the Request object.

call dies on error, giving a WebService::CloudFlare::Host::Exception object and should be run in an eval or with Try::Tiny.

STANDARD OBJECT METHODS

Standard Request Object

The host key is dynamically inserted into the Requests.

Standard Response Object

The following methods are avilable on standard Response objects.

result: The result sent from the API: 'success' or 'error'.
message: If the result is 'error', a message will be set with a user-readable explaination of the error; otherwise, this method will not exist.
code: If the result is 'error', a code will be set. This error can be found at http://www.cloudflare.com/docs/host-api.html.

API CALLS

UserCreate

The UserCreate API call creates a user for the CloudFlare service, as if they had signed up through CloudFlare's website.

my $response = eval { $CloudFlare->call('UserCreate', email => 'Casey.Klein@partydown.com', pass => 'omgPassword', unique_id => '506172747920446f776e203c33205521', )};

Request

The request uses the following parameters:

email: The email address that the end-user can use to sign into the CloudFlare service.
pass: The password the user can use to sign into the CloudFlare service. This should not be recorded on the Hosting Provider's side.
user: A username for the user. This is used in saluations and emails from CloudFlare. It has no bearing in the rest of the API.
unique_id: A unique id that may be used for UserLookup calls (as opposed to the user's email address).
clobber: When set to 1, a user's unique_id can be replaced with a new unique_id.

Response

printf("Created account for %s, with Unique ID => %s, " . "User Key => %s, and API Key => %s", $response->unique_id, $response->user_key, $response->api_key );

The response sets the following methods:

api_key: This API key allows a hosting provider to act as the user. All user API requests can be completed with this key.
email: This is the registered email account for the CloudFlare user.
user_key: This user_key is used to make Hosting API calls, specifically the ZoneSet, ZoneDelete, and ZoneLookup API calls.
unique_id: This can be used instead of the email address to do UserLookup calls.
username: The username.

UserAuth

The UserAuth API call gives the hosting provider access to the User's account. The call returns a user_key as well as the api_key and authenticates the Hosting Provider to perform actions as the user.

Request

my $response = eval { $CloudFlare->call('UserAuth', email => 'Casey.Klein@partydown.com', pass => 'omgPassword', ) };

The request uses the following parameters:

email: The email address that the user used to register the account with CloudFlare.
pass: The password the user uses to login to CloudFlare. This should not be stored on a hosting provider's side.
unique_id: A unique_id that may be used to perform UserLookup API calls.
clobber: If true, the unique_id can be clobbered.

Response

The response sets the following methods:

api_key: This API key allows a hosting provider to act as the user. All user API requests can be completed with this key.
email: This is the registered email account for the CloudFlare user.
user_key: This user_key is used to make Hosting API calls, specifically the ZoneSet, ZoneDelete, and ZoneLookup API calls.
unique_id: This can be used instead of the email address to do UserLookup calls.

UserLookup

The UserLookup API call gives a hosting provider the ablity to find information on a user account that it has access to through either the unique_id or the email address that was used in UserAuth or UserCreate API calls.

Request

my $response = eval { $CloudFlare->call('UserLookup', email => 'Casey.Klein@partydown.com', ) };

The request uses the following parameters:

email: The email address that was used in UserCreate or UserAuth API call. This is required if unique_id is not set.
unique_id: The unique_id that was last set in UserCreate or UserAuth API call. This is required if email is not set.

Response

The response sets the following methods:

api_key: This API key allows a hosting provider to act as the user. All user API requests can be completed with this key.
email: This is the registered email account for the CloudFlare user.
user_key: This user_key is used to make Hosting API calls, specifically the ZoneSet, ZoneDelete, and ZoneLookup API calls.
unique_id: This can be used instead of the email address to do UserLookup calls.
user_authed: True if the hosting provider has access to this user.
user_exists: True if the user exists in the CloudFlare system.
zones: A list of zones that the user has associated with his or her account.

ZoneSet

This associates a zone with the CloudFlare service for the user whose user_key is used.

Request

my $response = eval { $CloudFlare->call('ZoneSet', user_key => 'e7af5f120e3240e7bfba063b5f62c922', resolve_to => '173.230.133.102', zone_name => 'partydown.com', subdomains => 'www', ) };

The request uses the following parameters:

user_key

The user_key provided by UserCreate, UserLookup, or UserAuth.

The zone will be associated with the user whose user_key is used.

resolve_to

The IP address or a CNAME that resolves to the origin server that hosts the content for the given website.

zone_name

The name of the domain.

subdomains

A comma-seperated list of the subdomains from the zone for which CloudFlare should act as a reverse proxy.

Response

The response sets the following methods:

zone_name: The name of the domain.
resolving: The origin server that has been recorded. The same as the one submitted in the Request.
forwarded: A hashref whose keys are the domain, and whose value is the CNAME that should be used in the DNS system to have the requests be processed by CloudFlare.
hosted: A hashref whose keys are the the domain name(s) that are hosted, and whose value is the resolving address.

ZoneDelete

This will remove a zone from being hosted by the user whose user_key is used, provided they are the ones hosting the zone.

Request

my $response = eval { $CloudFlare->call('ZoneDelete', user_key => 'e7af5f120e3240e7bfba063b5f62c922', zone_name => 'partydown.com', ) };

The request uses the following parameters:

user_key: The user_key of the user whose zone is being removed from CloudFlare.
zone_name: The name of the zone to be removed.

Response

The response sets the following methods:

zone_name: The name of the zone from the Request.
zone_deleted: True if the zone was deleted.

ZoneLookup

Find information on a zone hosted by a given user_key.

Request

my $response = eval { $CloudFlare->call('ZoneLookup', user_key => 'e7af5f120e3240e7bfba063b5f62c922', zone_name => 'partydown.com', ) };

The request uses the following parameters:

user_key: The user_key of the user whose zone is being removed from CloudFlare.
zone_name: The name of the zone to be removed.

Response

The response sets the following methods:

zone_name
resolving: The origin server that has been recorded. The same as the one submitted in the Request.
forwarded: A hashref whose keys are the domain, and whose value is the CNAME that should be used in the DNS system to have the requests be processed by CloudFlare.
hosted: A hashref whose keys are the the domain name(s) that are hosted, and whose value is the resolving address.
zone_exists: True if the zone exists in the CloudFlare service.
zone_hosted: True if the zone is hosted by this user_key.

CREATING API CALLS

TBD

Request Classes

Response Classes

AUTHOR

SymKat <symkat@symkat.com>

COPYRIGHT AND LICENSE

This is free software licensed under a BSD-Style License. Please see the LICENSE file included in this package for more detailed information.

AVAILABILITY

The latest version of this software is available through GitHub at https://github.com/symkat/webservice-cloudflare-host/

To install WebService::CloudFlare::Host, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WebService::CloudFlare::Host

CPAN shell

perl -MCPAN -e shell
install WebService::CloudFlare::Host

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

STANDARD OBJECT METHODS

Standard Request Object

Standard Response Object

API CALLS

UserCreate

Request

Response

UserAuth

Request

Response

UserLookup

Request

Response

ZoneSet

Request

Response

ZoneDelete

Request

Response

ZoneLookup

Request

Response

CREATING API CALLS

Request Classes

Response Classes

AUTHOR

COPYRIGHT AND LICENSE

AVAILABILITY

Module Install Instructions