README.md
Ruby client library for automating DataCentred account management.
[www.datacentred.co.uk](https://www.datacentred.co.uk)
[](https://circleci.com/gh/datacentred/datacentred-api-ruby)
[](http://badge.fury.io/rb/datacentred) [](https://codeclimate.com/github/datacentred/datacentred-api-ruby) [](https://coveralls.io/github/datacentred/datacentred-api-ruby?branch=master)
# Installation
```
gem install datacentred
```
or
(in Gemfile or .gemspec)
```ruby
gem 'datacentred'
```
then
```ruby
require 'datacentred'
```
# Usage
This API allows you to automate operations against your DataCentred account.
Operations include:
* Creating and managing users;
* Creating and managing roles for users;
* Managing OpenStack Project creation, quota adjustments, and user assignments;
* Viewing detailed usage/billing information for your account.
## Authentication
The API uses two pieces of information to authenticate access.
A unique access key specific to your DataCentred account, and a secret key which is generated once.
To get started:
1. Find your API access key and secret key at [my.datacentred.io](https://my.datacentred.io)
2. Set your credentials by exporting your access key and secret key as environment variables:
```
export DATACENTRED_ACCESS="my_access"
export DATACENTRED_SECRET="my_secret"
```
Or setting your keys manually using the following methods:
```ruby
Datacentred.access_key = 'my_access'
Datacentred.secret_key = 'my_secret'
```
NOTE: If you use this approach, the gem will ignore any values assigned to the environment variables.
## Usage Examples
The `User`, `Project`, and `Role` entities all support CRUD operations via the following methods:
* `.all` - returns an index of all entities of this type.
* `.create params` - creates a new entity where `params` is a hash of properties.
* `.find id` - finds the entity via the unique identifier `id`.
returned objects can be edited and deleted:
* `object.name = "Foo"` - changes the `name` property to `Foo`.
* `object.save` - saves any object changes so they persist on the server.
* `object.destroy` - removes the object from the server.
Here are some worked examples:
### List all available users
```ruby
Datacentred::User.all
# => [#<Datacentred::Model::User id="2bd21ee25cde40fdb9454954e4fbb4b5", ...>, ...]
```
### Find a user by id
```ruby
user = Datacentred::User.find "2bd21ee25cde40fdb9454954e4fbb4b5"
# => #<Datacentred::Model::User id="2bd21ee25cde40fdb9454954e4fbb4b5", ...>
```
### Update a project
```ruby
project = Datacentred::Project.find "6d5277716c4b10d2177814af50b77175"
project.name = "Foo"
project.save
# => #<Datacentred::Model::Project id="6d5277716c4b10d2177814af50b77175", name= "Foo", ...>
```
### Create a role
Acceptable permissions are: 'api.read', 'cloud.read', 'roles.modify', 'roles.read', 'storage.read', 'tickets.modify', 'usage.read'.
```ruby
role = Datacentred::Role.create name: "foo", permissions: ["usage.read"]
# => #<Datacentred::Model::Role id="654f423e-646a-4742-849d-d8c9ab9b4f39", name="foo", admin=false, permissions=["usage.read"] ...>
```
### Add a user to a role
```ruby
role = Dataentred::Role.find "654f423e-646a-4742-849d-d8c9ab9b4f39"
user = Datacentred::User.find "2bd21ee25cde40fdb9454954e4fbb4b5"
role.add_user user
# => true
```
### Remove a user from a project
```ruby
user = Datacentred::User.find "2bd21ee25cde40fdb9454954e4fbb4b5"
project = Datacentred::Project.find "6d5277716c4b10d2177814af50b77175"
project.remove_user user
# => true
```
### Get usage data for a given year and month
Usage data is returned simply by supplying a year and a month. If the year/month are current then the data will be as recent as the time contained within the `last_updated_at` property.
```ruby
@usage = Datacentred::Usage.find 2017, 6
# => #<Datacentred::Model::Usage last_updated_at=2017-07-12 09:46:54 UTC, projects=[{:id=>"37033518a4514f12adeb8346ac3f188c"
@usage.projects.first.name
# => "wyld_stallyns"
@usage.projects.first.usage.instances.first.current_flavor.name
=> "dc1.1x1"
```
## Errors
The gem may raise the following standard errors:
* `Unauthorized` - Your credentials are incorrect or your account isn't authorized for API access.
* `NotFound` - The entity you referred to can't be found with the ID you supplied.
* `UnprocessableEntity` - There was a validation issue with your request (only applies to create/delete/update operations)
## Documentation
Full documentation is also available via https://datacentred.github.io/datacentred-api-ruby/
## API Reference Manual
Please check out the [DataCentred API Documentation](https://my.datacentred.io/api/docs/v1) for a comprehensive description of the API itself.