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.