/ 
OpenStack-Client-1.0002_0001
River stage one • 1 direct dependent • 1 total dependent
/ OpenStack::Client

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:

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

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

There exists a second form of call that allows one to pass in $headers as an optional input parameter (hash reference), which allows one to directly modify the following headers sent along with the request; when used, $headers must be placed in the second position after $method.

Headers are case insensitive, and if one sets duplicate headers, one of them will get set; but there are no guarantess which one will. Repeat headers at your own risk.

Accept

Defaults to application/json, text/plain.

Accept-Encoding

Defaults to identity, gzip, deflate, compress.

Content-Type

Defaults to application/json, although some API calls (e.g., a PATCH) expect a different type; the the case of an image update, the expected type is application/openstack-images-v2.1-json-patch or some version thereof.

For example, the following shows how one may update image metadata using the PATCH method supported by version 2 of the Image API.

In the example below, @image_updates is an array of hash references of the structure defined by the PATCH RFC (6902) governing "JavaScript Object Notation (JSON) Patch"; i.e., operations consisting of add, replace, or delete.

my $headers  = { 'Content-Type' => 'application/openstack-images-v2.1-json-patch' };
my $response = $glance->call( q{PATCH}, $headers, qq[/v2/images/$image->{id}], \@image_updates )

And except for x-auth-token, any additional token will be added to the request.

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>

CONTRIBUTORS

Brett Estrade <brett@cpanel.net>

COPYRIGHT

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