NAME

OpenStack::Client - A cute little client to OpenStack services

SYNOPSIS

#
# First, connect to an API endpoint via the Keystone authorization service
#
use OpenStack::Client::Auth ();

my $auth = OpenStack::Client::Auth->new('http://openstack.foo.bar:5000/v2.0',
    'tenant'   => $ENV{'OS_TENANT_NAME'},
    'username' => $ENV{'OS_USERNAME'},
    'password' => $ENV{'OS_PASSWORD'}
);

my $glance = $auth->service('image',
    'region' => $ENV{'OS_REGION_NAME'}
);

my @images = $glance->all('/v2/images', 'images');

#
# Or, connect directly to an API endpoint by URI
#
use OpenStack::Client ();

my $glance = OpenStack::Client->new('http://glance.foo.bar:9292',
    'token' => {
        'id' => 'foo'
    }
);

my @images = $glance->all('/v2/images', 'images');

DESCRIPTION

OpenStack::Client is a no-frills OpenStack API client which provides generic access to OpenStack APIs with minimal remote service discovery facilities; with a minimal client, the key understanding of the remote services are primarily predicated on an understanding of the authoritative OpenStack API documentation:

http://developer.openstack.org/api-ref.html

Authorization, authentication, and access to OpenStack services such as the OpenStack Compute and Networking APIs is made convenient by OpenStack::Client::Auth. Further, some small handling of response body data such as obtaining the full resultset of a paginated response is handled for convenience.

Ordinarily, a client can be obtained conveniently by using the services() method on a OpenStack::Client::Auth object.

INSTANTIATION

OpenStack::Client->new($endpoint, %opts)

Create a new OpenStack::Client object connected to the specified $endpoint. The following values may be specified in %opts:

• token

  A token obtained from a OpenStack::Client::Auth object.

INSTANCE METHODS

These methods are useful for identifying key attributes of an OpenStack service endpoint client.

$client->endpoint()

Return the absolute HTTP URI to the endpoint this client provides access to.

$client->token()

If a token object was specified when creating $client, then return it.

PERFORMING REMOTE CALLS

$client->call($method, $path, $body)

Perform a call to the service endpoint using the HTTP method $method, accessing the resource $path (relative to the absolute endpoint URI), passing an arbitrary value in $body that is to be encoded to JSON as a request body. This method may return the following:

• For application/json: A decoded JSON object

• For other response types: The unmodified response body

In exceptional conditions (such as when the service returns a 4xx or 5xx HTTP response), the client will die() with the raw text response from the HTTP service, indicating the nature of the service-side failure to service the current call.

FETCHING REMOTE RESOURCES

$client->get($path, %opts)

Issue an HTTP GET request for resource $path. The keys and values specified in %opts will be URL encoded and appended to $path when forming the request. Response bodies are decoded as per $client->call().

$client->each($path, $opts, $callback)

$client->each($path, $callback)

Issue an HTTP GET request for the resource $path, while passing each decoded response object to $callback in a single argument. $opts is taken to be a HASH reference containing zero or more key-value pairs to be URL encoded as parameters to each GET request made.

$client->every($path, $attribute, $opts, $callback)

$client->every($path, $attribute, $callback)

Perform a series of HTTP GET request for the resource $path, decoding the result set and passing each value within each physical JSON response object's attribute named $attribute, to the callback $callback as a single argument. $opts is taken to be a HASH reference containing zero or more key-value pairs to be URL encoded as parameters to each GET request made.

$client->all($path, $attribute, $opts)

$client->all($path, $attribute)

Perform a series of HTTP GET requests for the resource $path, decoding the result set and returning a list of all items found within each response body's attribute named $attribute. $opts is taken to be a HASH reference containing zero or more key-value pairs to be URL encoded as parameters to each GET request made.

CREATING AND UPDATING REMOTE RESOURCES

$client->put($path, $body)

Issue an HTTP PUT request to the resource at $path, in the form of a JSON encoding of the contents of $body.

$client->post($path, $body)

Issue an HTTP POST request to the resource at $path, in the form of a JSON encoding of the contents of $body.

DELETING REMOTE RESOURCES

$client->delete($path)

Issue an HTTP DELETE request of the resource at $path.

SEE ALSO

OpenStack::Client::Auth

The OpenStack Keystone authentication and authorization interface

AUTHOR

Written by Alexandra Hrefna Hilmisdóttir <xan@cpanel.net>

COPYRIGHT

Copyright (c) 2015 cPanel, Inc. Released under the terms of the MIT license. See LICENSE for further details.