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 = Aviator::Session.new(
              :config_file => 'path/to/aviator.yml',
              :environment => :production
            )

openstack.authenticate
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:
  compute
  identity
  image
  metering
  volume


$ 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

Parameters:
 +-------------+----------+-------------+
 | 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
    params.name = value
  end

Links:
  documentation:
    http://docs.openstack.org/api/openstack-compute/2/content/CreateServers.html

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',
         'http://docs.openstack.org/api/openstack-compute/2/content/CreateServers.html'

    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]
      end

      p
    end


    def headers
      super
    end


    def http_method
      :post
    end


    def url
      "#{ base_url }/servers"
    end

  end

end

Browse the rest of the request files here.


Installation

Add this line to your application's Gemfile:

        gem 'aviator'
        

Or if you want to live on the edge:

        gem 'aviator', :git => 'git@github.com:aviator/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.