Cabal::API

Cabal is a simple system for SSH key distribution and consumption. This is the HTTP API that acts as the basis for both of those operations.

Installation

Add this line to your application's Gemfile:

gem 'cabal-api', require: 'cabal/api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install cabal-api

Usage

This API is implemented via Grape, which means that you can mount it the same way that you can any Rack application. You'll need a Redis endpoint for the API to use (it defaults to redis://localhost:6379), and this is configured via the REDIS_URL environment variable.

Here's an example config.ru that mounts the API to the "/api" namespace:

require 'cabal/api'

map "/api" do
  run Cabal::API::Base
end

You can then start that configuration like so:

REDIS_URL="redis://your-redis-server:port/db" rackup config.ru

APIv1

The v1 API is entirely public (no authenticated routes). The routes for this version are as follows (provided that the API is mounted on "/api"):

  • GET /api/v1/key/clustername

This returns the public key for the given cluster name. If the cluster is not already known, it is created and a key is generated. Supported formats are:

  • text - Returns the key raw
  • json - Returns an object with name and public_ssh_key attributes
  • xml - Returns a "hash" document with name and public_ssh_key elements

APIv2

The v2 API is made up of both public and private routes. Authentication is performed by setting the Authorization request header to API_KEY:API_SECRET prior to performing the request.

  • (public) GET /api/v2/key/clustername

This route is exactly equivalent to the v1 key route.

  • (private) GET /api/v2/private-key/clustername

Returns the private key for the requested cluster. If the cluster is not already known, the request results in a 404. If authentication credentials are missing or invalid, the request results in a 404. Otherwise, the result depends on format:

  • text - Returns the raw key
  • json - Returns an object with name and private_ssh_key attributes
  • xml - Returns a "hash" document with name and private_ssh_key elements

APIv2

The v3 API is made up of both public and private routes. Authentication is performed by setting the Authorization request header to API_KEY:API_SECRET prior to performing the request.

  • (public) GET /api/v3/key/clustername

This route is exactly equivalent to the v1 key route.

  • (private) GET /api/v3/private-key/clustername

This route is exactly equivalent to the v2 private-key route.

  • (private) GET /api/v3/clusters

Returns the names of the clusters known to the API in the following format:

  • text - Returns a list of cluster names, one per line
  • json - Returns an array of objects with name attributes
  • xml - Returns an "array" document containing "hash" elements with a name element

Development

Branches and releases for this project are managed by git-flow.

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

Contributing

Note: Please base all feature branches on the develop branch.

  1. Fork it ( https://github.com/engineyard/cabal-api/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request against the develop branch