/ 
HTTP-API-Client-1.05
/ HTTP::API::Client

NAME

HTTP::API::Client - API Client

USAGE

use HTTP::API::Client;

my $ua1 = HTTP::API::Client->new;
my $ua2 = HTTP::API::Client->new(base_url => URI->new( $url ), pre_defined_headers => { X_COMPANY => 'ABC LTD' } );
my $ua3 = HTTP::API::Client->new(base_url => URI->new( $url ), pre_defined_data => { api_key => 123 } );

$ua->send( $method, $url, \%data, \%header );

Send short hand methods - get, post, head, put and delete

Example:

$ua->get( $url ) same as $ua->send( GET, $url );
$ua->post( $url, \%data, \%headers ) same as $ua->send( GET, $url, \%data, \%headers );

Get Json Data - grab the content body from the response and json decode

$ua = HTTP::API::Client->new(base_url => URI->new("http://google.com"));
$ua->get("/search" => { q => "something" });
my $hashref_from_decoded_json_string = $ua->json_response;
## ps. this is just an example to get json from a rest api

Send a query string to server

$ua = HTTP::API::Client->new( content_type => "application/x-www-form-urlencoded" );
$ua->post("http://google.com", { q => "something" });
my $response = $ua->last_response; ## is a HTTP::Response object

At the moment, only support query string and json data in and out

ENVIRONMENT VARIABLES

These enviornment variables expose the controls without changing the existing code.

HTTP VARIABLES

HTTP_USERNAME   - basic auth username
HTTP_PASSWORD   - basic auth password
HTTP_AUTH_TOKEN - basic auth token string
HTTP_CHARSET    - content type charset. default utf8
HTTP_TIMEOUT    - timeout the request for ??? seconds. default 60 seconds.
SSL_VERIFY      - verify ssl url. default is off

DEBUG VARIABLES

DEBUG_IN_OUT               - print out request and response in string to STDERR
DEBUG_SEND_OUT             - print out request in string to STDERR
DEBUG_RESPONSE             - print out response in string to STDERR
DEBUG_RESPONSE_HEADER_ONLY - print out response header only without the body
DEBUG_RESPONSE_IF_FAIL     - narrows DEBUG_IN_OUT/DEBUG_RESPONSE to only print
                             on a failed response. Does nothing by itself -
                             DEBUG_IN_OUT or DEBUG_RESPONSE must also be set.

RETRY VARIABLES

RETRY_FAIL_RESPONSE  - number of time to retry if resposne comes back is failed. default 0 retry
RETRY_FAIL_STATUS    - only retry if specified status code. e.g. 500,404
RETRY_DELAY          - retry with wait time of ??? seconds in between

METHODS

get / post / put / head / delete ($path, \%data, \%headers, \%events)

Shorthand for send($METHOD, $path, \%data, \%headers, \%events). $path is appended to the base_url attribute if one was given. Returns whatever send() returns - normally an HTTP::Response.

send($method, $path, \%data, \%headers, \%events)

Builds and sends one HTTP request, retrying per "ENVIRONMENT VARIABLES" if configured. %data and %headers are merged over pre_defined_data and pre_defined_headers. %events are the per-call callbacks documented under new_request() below. Sets and returns the last_response attribute.

Passing $events->{test_request_object} = 1 makes it return the built HTTP::Request instead of sending it - the way this module's own test suite inspects what would have gone out.

json_response

Decode the last_response body as JSON and return the resulting hashref. Never dies - a missing response or invalid JSON comes back as { status => "error", error => $message } instead.

kvp_response

Parse the last_response body as a key=value&key=value query string and return it as a hashref. Returns {} if no request has been made yet, or the response body is empty.

new_request(%options)

Builds the HTTP::Request for one call. This is where the %events callbacks passed to send() are read: before_headers, headers_keys / add_headers_keys (which header keys to consider, in what order), before_header/after_header keyed by header name, and after_header_keys - the hooks used to compute things like a signature header from other data at build time. See t/04_callbacks.t for a worked example (API key + signature).

convert_data(%options)

Turn %options's data hashref into the request body, according to content type: JSON via kvp2json() if the content type contains json, a query string via kvp2str() if it is exactly application/x-www-form-urlencoded. Any other content type returns an empty string for empty data, or dies naming the content type - there is no generic way to serialize arbitrary data into an arbitrary content type.