symkat > WebService-CloudFlare-Host-000100 > WebService::CloudFlare::Host

Download:
WebService-CloudFlare-Host-000100.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 000100   Source  

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/

syntax highlighting: