# 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](https://metacpan.org/pod/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](https://metacpan.org/pod/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](https://metacpan.org/pod/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](https://metacpan.org/pod/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.