README.asciidoc

== Gophercloud -- V0.2.0 image:https://secure.travis-ci.org/rackspace/gophercloud.png?branch=v0.2.0["build status",link="https://travis-ci.org/rackspace/gophercloud"]

Gophercloud currently lets you authenticate with OpenStack providers to create and manage servers (compute service) and objects (object-storage service).
We are working on extending the API to further include block storage, DNS, databases, security groups, and other features.

WARNING: This library is still in the very early stages of development. Unless you want to contribute, it probably isn't what you want.  Yet.

=== Outstanding Features

1.  Apache 2.0 License, making Gophercloud friendly to commercial and open-source enterprises alike.
2.  Gophercloud is one of the most actively maintained Go SDKs for OpenStack.
3.  Gophercloud supports Identity V2, Nova V2, and Object Storage V1 APIs.  More coming soon!
5.  Gophercloud supports automatic reauthentication upon auth token timeout, if enabled by your software.
6.  Gophercloud is the only SDK implementation with actual acceptance-level integration tests.

=== Dependencies
* Go 1.*  (For information on installing Go and setting up your environment, go link:https://golang.org/doc/install[here])
* git

=== Getting the code

To download Gophercloud, simpy run
```
go get github.com/rackspace/gophercloud
```
It will automatically retrieve all dependencies. Goperhcloud and its dependencies will be located within your $GOPATH.

=== Running the tests

Gophercloud has both unit tests and acceptance (integration) tests.

To run the unit tests, run
```
go test -v github.com/rackspace/gophercloud
```
from the Gophercloud root directory.

To run the acceptance tests, run
```
go test -v -tags acceptance github.com/rackspace/gophercloud
```
*Note: Running the acceptance tests briefly creates (and deletes) real resources. You may incur costsfrom your provider by running these.*

To run specific tests, use a regular expression with the `run` flag. For example, to just run the authentication test (named TestAuthentication), run
```
go test -v -run "Authentication" -tags acceptance github.com/rackspace/gophercloud
```

=== What Does it Look Like?

The Gophercloud 0.1.0 and earlier APIs are now deprecated and obsolete.
No new feature development will occur for 0.1.0 or 0.0.0.
However, we will accept and provide bug fixes for these APIs.
Please refer to the acceptance tests in the master brach for code examples using the v0.1.0 API.
The most up to date documentation for version 0.1.x can be found at link:http://godoc.org/github.com/rackspace/gophercloud[our Godoc.org documentation].

We are working on a new API that provides much better support for extensions, pagination, and other features that proved difficult to implement before.
This new API will be substantially more Go-idiomatic as well; one of the complaints received about 0.1.x and earlier is that it didn't "feel" right.
To see what this new API is going to look like, you can look at the code examples up on the link:http://gophercloud.io/docs.html[Gophercloud website].
If you're interested in tracking progress, note that features for version 0.2.0 will appear in the `v0.2.0` branch until merged to master.

=== How can I Contribute?

After using Gophercloud for a while, you might find that it lacks some useful feature, or that existing behavior seems buggy.  We welcome contributions from our users for both missing functionality as well as for bug fixes.  We encourage contributors to collaborate with the link:http://gophercloud.io/community.html[Gophercloud community.]

Finally, Gophercloud maintains its own link:http://gophercloud.io[announcements and updates blog.]
Feel free to check back now and again to see what's new.

== License

Copyright (C) 2013, 2014 Rackspace, Inc.

Licensed under the Apache License, Version 2.0