README.md in datacentred-0.1.1pre vs README.md in datacentred-1.1.1
- old
+ new
@@ -1,2 +1,160 @@
-# datacentred-api-ruby
-Gem wrapper for Datacentred API.
+
+
+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/keybase-core) [](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.
+* `.update id, params` - updates the entity identified by `id` with the hash of properties defined by `params`.
+* `.find id` - finds the entity via the unique identifier `id`.
+* `.destroy id` - removes the entity via the unique identifier `id`.
+
+Here are some worked examples:
+
+### List all available users
+
+```ruby
+Datacentred::User.all
+# => [#<Datacentred::Model::User id="2bd21ee25cde40fdb9454954e4fbb4b5", ...>, ...]
+```
+
+### Find a user by id
+
+```ruby
+Datacentred::User.find "2bd21ee25cde40fdb9454954e4fbb4b5"
+# => #<Datacentred::Model::User id="2bd21ee25cde40fdb9454954e4fbb4b5", ...>
+```
+
+### Update a project
+
+```ruby
+Datacentred::Project.update "6d5277716c4b10d2177814af50b77175", name: "Foo"
+# => #<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
+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
+Datacentred::Role.add_user role_id: "654f423e-646a-4742-849d-d8c9ab9b4f39", user_id: "2bd21ee25cde40fdb9454954e4fbb4b5"
+# => true
+```
+
+### Remove a user from a project
+
+```ruby
+Datacentred::Project.remove_user project_id: "6d5277716c4b10d2177814af50b77175", user_id: "2bd21ee25cde40fdb9454954e4fbb4b5"
+# => 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"
+```
+
+## Schemas
+
+There are JSON schemas available for each entity in the gem:
+
+* Projects: https://my.datacentred.io/api/schemas/project
+* Roles: https://my.datacentred.io/api/schemas/role
+* Usage: https://my.datacentred.io/api/schemas/usage
+* User: https://my.datacentred.io/api/schemas/user
+
+## 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.