Fork me on GitHub

A Framework for Writing REST API Clients

Aviator is a framework for writing REST API clients. To help get you started, it includes a few OpenStack request files you can use for educational purposes.

require 'aviator'

openstack =
              :config_file => 'path/to/aviator.yml',
              :environment => :production

response = openstack.request :identity_service, :list_tenants

puts response[:body]

See the API docs for more information on how to send requests.

Configure for multiple environments

The config file is a simple YAML file that can have one or more environment definitions.

  provider: openstack
    name: identity
    host_uri: ''
    request: create_token
    validator: list_tenants
    api_version: v2
    token_id: 2c963f5512d067b24fdc312707c80c7a6d3d261b
    tenant_name: admin

  provider: openstack
    name: identity
    host_uri: 'http://devstack:5000/v2.0'
    request: create_token
    validator: list_tenants
    username: myusername
    password: mypassword
    tenant_name: myproject

The auth_credentials in the config file are optional and can be supplied at runtime. For more information see the documentation.

Browse the available requests

Aviator comes with a handy dandy command line interface called describe that allows you to inspect the available requests in the library:

$ aviator describe openstack
Available services for openstack:

$ aviator describe openstack compute
Available requests for openstack compute_service:
  v2 admin confirm_server_resize
  v2 admin get_host_details
  v2 admin list_hosts
  v2 admin resize_server
  v2 admin revert_server_resize
  v2 public change_admin_password
  v2 public create_image
  v2 public create_server

$ aviator describe openstack compute v2 public create_server
Request: create_server

 | NAME        | REQUIRED | ALIAS       |
 | accessIPv4  |    N     | access_ipv4 |
 | accessIPv6  |    N     | access_ipv6 |
 | adminPass   |    N     | admin_pass  |
 | flavorRef   |    Y     | flavor_ref  |
 | imageRef    |    Y     | image_ref   |
 | metadata    |    N     |             |
 | name        |    Y     |             |
 | networks    |    N     |             |
 | personality |    N     |             |

Sample Code:
  session.request(:compute_service, :create_server) do |params|
    params.access_ipv4 = value
    params.access_ipv6 = value
    params.admin_pass = value
    params.metadata = value
    params.networks = value
    params.personality = value
    params.image_ref = value
    params.flavor_ref = value = value


TIP: On OS X, command click on the link to open it in a browser.

...Or Read the Code Directly

We designed a DSL for the request definition files so that they are easy to read, easy to add to, and pretty much be self documenting (in fact, the same code is used by the describe CLI tool). For instance, here is the actual code for the create_server request:

module Aviator

  define_request :create_server, :inherit => [:openstack, :common, :v2, :public, :base] do

    meta :service, :compute

    link 'documentation',

    param :accessIPv4,  :required => false, :alias => :access_ipv4
    param :accessIPv6,  :required => false, :alias => :access_ipv6
    param :adminPass,   :required => false, :alias => :admin_pass
    param :imageRef,    :required => true,  :alias => :image_ref
    param :flavorRef,   :required => true,  :alias => :flavor_ref
    param :metadata,    :required => false
    param :name,        :required => true
    param :networks,    :required => false
    param :personality, :required => false

    def body
      p = {
        :server => {
          :flavorRef => params[:flavorRef],
          :imageRef  => params[:imageRef],
          :name      => params[:name]

      [:adminPass, :metadata, :personality, :networks, :accessIPv4, :accessIPv6].each do |key|
        p[:server][key] = params[key] if params[key]


    def headers

    def http_method

    def url
      "#{ base_url }/servers"



Browse the rest of the request files here.

Session Management API

Serialize the session information for caching. The output is in plaintext JSON which contains sensitive information. You are responsible for securing that.

session = ... )
str = session.dump

Creating a new Session object from a session dump is just as easy.

session = Aviator::Session.load(str)

Depending on how old the loaded session dump is, its session data may already be expired. Check if it's still current by calling Session#validate and reauthenticate as needed.

session.authenticate unless session.validate

Need a way to persist session dumps? Give Aviator::SessionPool a try!

Install It Now!

Add this line to your application's Gemfile:

gem 'aviator'

Or if you want to live on the edge:

gem 'aviator', :git => '', :branch => 'master'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install aviator

API documentation

API documentation is still a work in progress, but we've made sure to fully cover the important ones:

Need Some Samples?

Check out the demo project for a quick sampling of how you can use Aviator.

Useful Links

Project Stats

Build Status Coverage Status Code Climate Gem Version