WebService::CloudFlare::Host - A client API For Hosting Partners
000100 (0.1.0)
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 );
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.
The only method used is call($api_call, %arguments).
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.
call
The host key is dynamically inserted into the Requests.
The following methods are avilable on standard Response objects.
The result sent from the API: 'success' or 'error'.
If the result is 'error', a message will be set with a user-readable explaination of the error; otherwise, this method will not exist.
If the result is 'error', a code will be set. This error can be found at http://www.cloudflare.com/docs/host-api.html.
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', )};
The request uses the following parameters:
The email address that the end-user can use to sign into the CloudFlare service.
The password the user can use to sign into the CloudFlare service. This should not be recorded on the Hosting Provider's side.
A username for the user. This is used in saluations and emails from CloudFlare. It has no bearing in the rest of the API.
A unique id that may be used for UserLookup calls (as opposed to the user's email address).
When set to 1, a user's unique_id can be replaced with a new unique_id.
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:
This API key allows a hosting provider to act as the user. All user API requests can be completed with this key.
This is the registered email account for the CloudFlare user.
This user_key is used to make Hosting API calls, specifically the ZoneSet, ZoneDelete, and ZoneLookup API calls.
This can be used instead of the email address to do UserLookup calls.
The username.
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.
my $response = eval { $CloudFlare->call('UserAuth', email => 'Casey.Klein@partydown.com', pass => 'omgPassword', ) };
The email address that the user used to register the account with CloudFlare.
The password the user uses to login to CloudFlare. This should not be stored on a hosting provider's side.
A unique_id that may be used to perform UserLookup API calls.
If true, the unique_id can be clobbered.
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.
my $response = eval { $CloudFlare->call('UserLookup', email => 'Casey.Klein@partydown.com', ) };
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.
email
True if the hosting provider has access to this user.
True if the user exists in the CloudFlare system.
A list of zones that the user has associated with his or her account.
This associates a zone with the CloudFlare service for the user whose user_key is used.
my $response = eval { $CloudFlare->call('ZoneSet', user_key => 'e7af5f120e3240e7bfba063b5f62c922', resolve_to => '173.230.133.102', zone_name => 'partydown.com', subdomains => 'www', ) };
The user_key provided by UserCreate, UserLookup, or UserAuth.
The zone will be associated with the user whose user_key is used.
The IP address or a CNAME that resolves to the origin server that hosts the content for the given website.
The name of the domain.
A comma-seperated list of the subdomains from the zone for which CloudFlare should act as a reverse proxy.
The origin server that has been recorded. The same as the one submitted in the Request.
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.
A hashref whose keys are the the domain name(s) that are hosted, and whose value is the resolving address.
This will remove a zone from being hosted by the user whose user_key is used, provided they are the ones hosting the zone.
my $response = eval { $CloudFlare->call('ZoneDelete', user_key => 'e7af5f120e3240e7bfba063b5f62c922', zone_name => 'partydown.com', ) };
The user_key of the user whose zone is being removed from CloudFlare.
The name of the zone to be removed.
The name of the zone from the Request.
True if the zone was deleted.
Find information on a zone hosted by a given user_key.
my $response = eval { $CloudFlare->call('ZoneLookup', user_key => 'e7af5f120e3240e7bfba063b5f62c922', zone_name => 'partydown.com', ) };
True if the zone exists in the CloudFlare service.
True if the zone is hosted by this user_key.
TBD
SymKat <symkat@symkat.com>
This is free software licensed under a BSD-Style License. Please see the LICENSE file included in this package for more detailed information.
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.