Fork me on GitHub

A Framework for Writing REST API Clients

Aviator is a framework for writing REST API clients. As a reference implementation, it includes a few OpenStack request classes 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]

It can handle Keystone v2 and v3 authentication data but there is no guarantee that all OpenStack API endpoints are supported. You will likely need to write some of the request files yourself.

To know which requests are available, you may use the built-in CLI tool describe:

$ 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


If you need to write request files, the DSL is simple enough to learn and you can start writing your own in 5~10 minutes. As an example, here is the request file for the create_server request mentioned above:

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.


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

It's is still a work in progress but I've made sure to cover the important ones:

Need Some Samples?

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

Other Links

Project Stats

Build Status Coverage Status Code Climate Gem Version

Absolutely Zero Warranty of Any Kind

This library is released under the MIT license, so have at it as you wish as long as it is within the boundaries of said license. If you have any questions, feel free to file it here. I don't make response time guarantees. This is a hobby project for me nowadays and I will work on it when I have time. Having said that, I usually find time near the weekend.